Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ their facts are verified against the CLI, so trust them over stale prose.
## Project Structure & Module Organization

- Source: Next.js + Nextra docs site using TypeScript.
- Content: MDX pages under `pages/` (route = file path). Example: `pages/sdk/wasmer-js/how-to/use-filesystem.mdx`.
- Content: MDX pages under `content/` (route = file path). Example: `content/runtime/js.mdx`.
- UI: React components in `components/` and `theme/src/components/`; site config in `theme.config.tsx` and `next.config.mjs`.
- Styling & assets: Tailwind config in `tailwind.config.js`, global styles in `styles/`, static files in `public/`, additional images in `assets/`.

Expand Down Expand Up @@ -50,7 +50,7 @@ their facts are verified against the CLI, so trust them over stale prose.
## Commit & Pull Request Guidelines

- Commits: Write clear, scoped messages in present tense (e.g., `docs: add wasm fs how-to`).
- PRs: Include a concise description, affected pages/components, screenshots or local URLs (e.g., `http://localhost:3000/sdk/...`) when visual changes apply, and link related issues.
- PRs: Include a concise description, affected pages/components, screenshots or local URLs (e.g., `http://localhost:3000/runtime/js`) when visual changes apply, and link related issues.
- CI: GitHub Actions build must pass (`.github/workflows/ci.yaml`). For deploys, main builds publish via Wasmer.

## Security & Deployment Notes
Expand Down
4 changes: 1 addition & 3 deletions app/layout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,11 @@ export default async function RootLayout({
}: Readonly<{
children: ReactNode
}>) {
const [rootPageMap, edgePageMap, registryPageMap, sdkPageMap, runtimePageMap] =
const [rootPageMap, edgePageMap, registryPageMap, runtimePageMap] =
await Promise.all([
getPageMap('/'),
getPageMap('/edge'),
getPageMap('/registry'),
getPageMap('/sdk'),
getPageMap('/runtime'),
])

Expand All @@ -37,7 +36,6 @@ export default async function RootLayout({
root: rootPageMap,
edge: edgePageMap,
registry: registryPageMap,
sdk: sdkPageMap,
runtime: runtimePageMap,
}}
>
Expand Down
1 change: 0 additions & 1 deletion components/DocsNavbarLinks.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ const sections = [
{ href: '/runtime', label: 'Runtime' },
{ href: '/registry', label: 'Registry' },
{ href: '/edge', label: 'Edge' },
{ href: '/sdk/wasmer-js', label: 'SDKs' },
]

function XLogoIcon() {
Expand Down
2 changes: 0 additions & 2 deletions components/DocsShell.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,13 @@ type DocsShellProps = {
root: PageMapItem[]
edge: PageMapItem[]
registry: PageMapItem[]
sdk: PageMapItem[]
runtime: PageMapItem[]
}
}

function getSection(pathname: string) {
if (pathname === '/edge' || pathname.startsWith('/edge/')) return 'edge'
if (pathname === '/registry' || pathname.startsWith('/registry/')) return 'registry'
if (pathname === '/sdk' || pathname.startsWith('/sdk/')) return 'sdk'
if (pathname === '/runtime' || pathname.startsWith('/runtime/')) return 'runtime'
return 'root'
}
Expand Down
4 changes: 0 additions & 4 deletions content/_meta.js
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,6 @@ export default {
"title": "Edge",
"display": "hidden"
},
"sdk": {
"title": "SDKs",
"display": "hidden"
},
"-- Developers": {
"type": "separator",
"title": "Developers"
Expand Down
8 changes: 4 additions & 4 deletions content/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ Welcome to the Wasmer Documentation! 👋

## SDKs

Wasmer is available in multiple programming languages and operating systems in the shape of SDKs.
Using these SDKs, it's possible to embed Wasmer modules compiled from other languages into your application.
We have set up the SDKs to allow using Wasmer easily anywhere:
Embed the Wasmer Runtime directly in your application and run packages in
local, capability-based sandboxes:

* [Wasmer JavaScript SDK](/sdk/wasmer-js): run your Wasmer packages in JavaScript
* [JavaScript SDK](/runtime/js): run Wasmer packages in Node.js or a browser
* [Python SDK](/runtime/python): run Wasmer packages inside a Python application

## Social

Expand Down
32 changes: 19 additions & 13 deletions content/install.mdx
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Install Wasmer

import { Callout } from '@components/nextra-theme';
import { Tabs, Tab } from '@components/nextra-theme';
import { Callout, Tab, Tabs } from '@components/nextra-theme';

Wasmer allows you to run applications either **standalone** (_via the CLI_) or **embedded** in [other languages](/sdk), such as Rust, C/C++, and JavaScript.
Run Wasmer as a standalone CLI or embed the Runtime in a JavaScript or Python
application with an SDK.

<Tabs items={['CLI (Bash)', 'CLI (PowerShell)', 'JS' /*, 'Python' */]}>
<Tabs items={['CLI (Bash)', 'CLI (PowerShell)', 'JavaScript SDK', 'Python SDK']}>
<Tab>
**Unix** (macOS, Linux):

Expand Down Expand Up @@ -65,22 +65,28 @@ Wasmer allows you to run applications either **standalone** (_via the CLI_) or *


<Tab>
**NPM**:
**npm**:

```bash /@wasmer/ /sdk/ copy
npm install @wasmer/sdk --save
```bash copy
npm install @wasmer/sdk
```

Bun:
**pnpm**:

```bash /@wasmer/ /sdk/ copy
bun install @wasmer/sdk --save
```bash copy
pnpm add @wasmer/sdk
```

Read the [Wasmer-JS SDK docs](/sdk/wasmer-js).

Import `@wasmer/sdk/node` in Node.js or `@wasmer/sdk/browser` in a
browser. Continue with the [JavaScript SDK guide](/runtime/js).
</Tab>

<Tab>
```bash copy
python -m pip install wasmer-sdk
```

{/* <SyncedTabs.Tab> `bash npm install wasmer` </SyncedTabs.Tab> <SyncedTabs.Tab> ```bash pip install wasmer ``` </SyncedTabs.Tab> */}
Continue with the [Python SDK guide](/runtime/python).
</Tab>

</Tabs>
32 changes: 23 additions & 9 deletions content/runtime.mdx
Original file line number Diff line number Diff line change
@@ -1,39 +1,53 @@
import { Cards, Card } from '@components/nextra-theme'
import { RunIcon } from '@components/icons/ProductIcons'

# Runtime Introduction
# Wasmer Runtime

The Wasmer Runtime is the engine that allows running WebAssembly modules and Wasmer packages anywhere.
The Wasmer Runtime runs WebAssembly modules and packages from the
[Wasmer Registry](/registry) in lightweight, capability-based sandboxes.
Use it as a command-line tool or embed it directly in a JavaScript or Python
application.

Wasmer can be used as a library from any programming language, or as a standalone runtime via the [`Wasmer CLI`](/runtime/cli).
| Interface | Best for | Install |
| --- | --- | --- |
| [Wasmer CLI](/runtime/cli) | Running packages from a terminal or script | `curl https://get.wasmer.io -sSfL \| sh` |
| [JavaScript SDK](/runtime/js) | Node.js and browser applications | `npm install @wasmer/sdk` |
| [Python SDK](/runtime/python) | Python applications and AI agents | `python -m pip install wasmer-sdk` |

All three interfaces use the same Wasmer packages and WASIX runtime. The SDKs
also expose a shared sandbox model for composing packages, files, environment
variables, networking, and long-running processes inside a host application.

## 🐥 First Steps
## First steps

To run a package, check out the [Getting Started](/runtime/get-started/) guide.
Start with one package, then choose the interface that fits your host
application.

<Cards>
<Card icon={<RunIcon width={20} height={20} />} title="Run your first package" href="/runtime/get-started" />
<Card icon={<RunIcon width={20} height={20} />} title="Run your first package" href="/runtime/get-started" />
<Card icon={<RunIcon width={20} height={20} />} title="JavaScript SDK" href="/runtime/js" />
<Card icon={<RunIcon width={20} height={20} />} title="Python SDK" href="/runtime/python" />
</Cards>

## Features

- **Secure** by default. No file, network, or environment access, unless explicitly enabled.
- **Fast**. Run WebAssembly at near-native speeds.
- **Pluggable**. Embeddable in multiple programming languages.
- **Embeddable**. Run sandboxes in JavaScript, Python, Rust, and other host
applications without a separate daemon.
- Compliant with the latest WebAssembly proposals (SIMD, Reference Types, Threads, ...)

## Backends

The Wasmer Runtime supports multiple backends, depending on your needs:

### Wasmer backends:
### Wasmer backends

- **Singlepass**: A single-pass compiler for fast compilation times and low memory usage.
- **Cranelift**: A fast compiler backend with a focus on compile times, and runtime performance.
- **LLVM**: A compiler backend that uses LLVM for optimization and code generation.

### Integration backends:
### Integration backends

- **Browser**: it allows running Wasmer fully in the browser (via `wasm-bindgen`).
- **V8**: it allows running Wasmer using the WebAssembly engine inside V8 (can run in interpreter mode or with JIT)
2 changes: 2 additions & 0 deletions content/runtime/_meta.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
export default {
"get-started": "Getting Started",
"js": "JavaScript SDK",
"python": "Python SDK",
"cli": "CLI",
"features": "Features",
"wasix": "WASIX",
Expand Down
6 changes: 6 additions & 0 deletions content/runtime/cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ import { Callout } from '@components/nextra-theme';

Run a WebAssembly file or Wasmer container.

<Callout type="info">
To embed the same packages and WASIX runtime in an application, use the
[JavaScript SDK](/runtime/js) or
[Python SDK](/runtime/python).
</Callout>

## Usage

### Run a Wasmer package
Expand Down
6 changes: 6 additions & 0 deletions content/runtime/features.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ import { Callout } from '@components/nextra-theme';

Wasmer is powered by [WebAssembly](https://webassembly.org).

The native CLI and Python SDK use Wasmer's native compiler backends. The
[JavaScript SDK](/runtime/js) targets the host JavaScript engine:
Node.js and browsers compile and execute WebAssembly while Wasmer supplies the
package, sandbox, filesystem, process, and WASIX layers. See the
[Python SDK guide](/runtime/python) for native embedding from Python.

Wasmer runs WebAssembly through a **backend**, and ships several depending on your needs. They fall into two groups by *how* they execute your code:

* Compiler backends: Wasmer compiles your WebAssembly to native machine code itself, then runs it directly on the CPU:
Expand Down
113 changes: 80 additions & 33 deletions content/runtime/get-started.mdx
Original file line number Diff line number Diff line change
@@ -1,59 +1,106 @@
import { Steps } from "@components/nextra-theme";
import { Callout } from "@components/nextra-theme";
import { Tab, Tabs } from "@components/nextra-theme";
import Install from "../../components/install.mdx";
import { Callout, Steps, Tab, Tabs } from '@components/nextra-theme';

# Run your first package

This page will guide you through installing Wasmer, and running a package from the Wasmer Registry.

The runtime can run any package published to the Wasmer Registry.
Wasmer packages run from the CLI or inside JavaScript and Python applications.
This guide uses the [`python/python`](https://wasmer.io/python/python) package
to calculate `1 + 1`; no system Python installation is used inside the
sandbox.

<Steps>

<Install />

### Run a package
### Install Wasmer

Let's say you want to run version `3.12` of the Wasmer package [`python/python`](https://wasmer.io/python/python) and execute the `-c "print(1+1)"` argument to print a result.
Choose the interface used by your host application:

<Tabs items={['CLI', 'JS' /*, 'Python'*/]}>
<Tabs items={['CLI', 'JavaScript', 'Python']}>
<Tab>
```bash copy /python/
wasmer run python/python@3.12 -- -c "print(1+1)"
On macOS or Linux:

```bash copy
curl https://get.wasmer.io -sSfL | sh
```

See [Install Wasmer](/install) for Windows and other installation methods.
</Tab>
<Tab>
```bash copy
npm install @wasmer/sdk
```

```js copy /python/
import { init, Wasmer } from "@wasmer/sdk";

await init();
let python = await Wasmer.fromRegistry("python/python@3.12");
let instance = await python.entrypoint.run({
args: ["-c", "print(1+1)"]
});
let output = await instance.wait();
Node.js and browser applications use the same package with different
entrypoints. This example uses Node.js.
</Tab>
<Tab>
```bash copy
python -m pip install wasmer-sdk
```

Published wheels support macOS and Linux on arm64 and x86_64.
</Tab>
{/*
</Tabs>

### Run the package

<Tabs items={['CLI', 'JavaScript', 'Python']}>
<Tab>
```bash copy
wasmer run python/python@=3.13.18 -- -c "print(1+1)"
```
</Tab>
<Tab>
```python copy
from wasmer import Wasmer
```javascript copy filename="index.mjs"
import { Wasmer } from '@wasmer/sdk/node';

python = Wasmer("python/python")
runner = python.entrypoint.run('-c "print(1+1)"')
print(python.stdout)
const wasmer = new Wasmer();
const sandbox = await wasmer.sandboxes.create({
packages: ['python/python@=3.13.18'],
});

const output = await sandbox
.command('python', ['-c', 'print(1+1)'])
.run();

console.log(output.text());
await sandbox.close();
await wasmer.close();
```
</Tab>
<Tab>
```python copy filename="main.py"
import asyncio

from wasmer_sdk import Wasmer


</Tab> */}
async def main() -> None:
async with Wasmer() as wasmer:
sandbox = await wasmer.sandboxes.create(
packages=['python/python@=3.13.18'],
)
async with sandbox:
output = await sandbox.command(
'python', ['-c', 'print(1+1)']
).run()
print(output.text())


asyncio.run(main())
```
</Tab>
</Tabs>

Each example prints `2`. The `@=` syntax pins the exact registry package
version so every run resolves the same artifact.

</Steps>

<Callout type="info" emoji="ℹ️">
You can also publish your packages to the Wasmer registry, so it can be used
everywhere. [Learn how](/registry/get-started).
<Callout type="info">
A sandbox can combine multiple packages and expose files, streams,
networking, and long-running processes. Continue with the
[JavaScript SDK](/runtime/js) or
[Python SDK](/runtime/python) guide.
</Callout>

You can also [publish your own package](/registry/get-started) to run it through
the CLI and every SDK.
Loading
Loading