Quickstart

Build with the workspace API

Your product opens a workspace by a key you choose, one per customer or project, and the same key returns the same workspace every time. Sign up, create a project API key and run a complete example in TypeScript, Python or the CLI. Each example runs a command, writes a file, suspends the workspace and reads the same file after resume. Then reach a port of the workspace at its own HTTPS URL.

Sign up and create an API key

1. Sign up at https://app.shardflux.dev/signup with Google, GitHub or a permanent email address (disposable addresses can't sign up).
2. Google and GitHub sign you in at once; with an email address, open the link in the verification email, which signs you in. Your organization and a Default project are already set up. The console opens on Setup, where you can finish trial verification and choose Open workspace without installing an SDK. Connecting from your code is optional; your first API key is available on the same page. Compute requires an active trial or paid plan: new accounts start the 7-day trial of Pro by verifying an established GitHub account or work domain and completing the $0 Stripe card check, or by subscribing to a paid plan ($9/mo Developer and up). Nothing is charged for the trial check. The trial applies to that organization; additional organizations need a paid plan.
3. Copy the key. It looks like sfk_<key id>_<secret>, can use every workspace tool, and is shown once. If you lose it, revoke it and create a new one under API keys (Create API key, with the workspace tools checked).

Put it in your shell's environment. Every example on this site reads it from SHARDFLUX_API_KEY:

export SHARDFLUX_API_KEY=sfk_...

API keys are server credentials: keep them out of browsers and repositories.

Or from a terminal

One command with the shard CLI (0.9.0+) does the same without a browser or a password:

npm i -g shardflux
shard signup --email you@example.com
eval "$(shard env)"

If npm reports EACCES or EPERM, use the user-directory install, which preserves npm config, PATH and other global packages.

signup creates the account, organization, project and an API key with every workspace tool at once, and saves the key in ~/.config/shardflux/credentials.json. shard verify emails you a 6-digit code that verifies the address. Compute starts once the organization has a card on file and an active trial or paid plan: verify an established GitHub account or work domain and complete the $0 Stripe card check on Usage & billing (or run shard billing trial --wait), or subscribe to a paid plan ($9/mo Developer and up); see Signup trial. env prints the key as export SHARDFLUX_API_KEY=..., so the eval line sets it for the examples below. For an account you already have, shard auth login --browser signs in through your browser (CLI 0.18.0+) and shard setup saves the organization, project and key. Every command takes --json, so a script or an agent can run the whole flow. See Accounts and sign-in.

TypeScript quick start

Needs Node.js 24 or later, which runs a .ts file directly.

mkdir shardflux-quickstart && cd shardflux-quickstart
npm init -y
npm pkg set type=module
npm install @shardflux/sdk

Save this as quickstart.ts:

import { workspace } from '@shardflux/sdk';

const ws = workspace('quickstart/demo', { template: 'default' }); // reads SHARDFLUX_API_KEY; no request yet

// 1. Run a command: the first call creates the workspace. Check that it worked.
const run = await ws.exec('python3 -c "print(40 + 2)"');
if (run.exitCode !== 0) throw new Error(`python3 exited ${run.exitCode}: ${run.stderr}`);
console.log(`created ${ws.created}, exit ${run.exitCode}, output ${run.stdout.trim()}`);

// 2. Write a file, then suspend the workspace and wait until the suspend has finished.
await ws.files.write('/home/user/notes.txt', 'hello from the SDK\n');
const full = await ws.open();
await full.suspend({ wait: true });
console.log(`after suspend: ${full.state}`);

// 3. The same key, from this process or any other: the workspace wakes, and the file is still there.
const again = workspace('quickstart/demo', { template: 'default' });
console.log(`notes.txt: ${(await again.files.readText('/home/user/notes.txt')).trim()}`);
console.log(`created ${again.created}`);

Run it:

node quickstart.ts

Expected output:

created true, exit 0, output 42
after suspend: suspended
notes.txt: hello from the SDK
created false

workspace(key, { template }) (0.15.0+) makes no request; its first call creates the workspace from the template (default is python-node-browser) and later calls reuse it, so a second run starts with created false. ws.open() returns the full workspace for lifecycle calls. suspend({ wait: true }) resolves once the suspend has finished; without wait it resolves as soon as the suspend is requested. See Lifecycle.

Python quick start

Needs Python 3.10 or later.

mkdir shardflux-quickstart && cd shardflux-quickstart
python3 -m venv .venv && . .venv/bin/activate
pip install shardflux

Save this as quickstart.py:

from shardflux import workspace

ws = workspace("quickstart/demo", template="default")  # reads SHARDFLUX_API_KEY; no request yet

# 1. Run a command: the first call creates the workspace. Check that it worked.
result = ws.exec("python3 -c 'print(40 + 2)'")
if result.exit_code != 0:
    raise RuntimeError(f"python3 exited {result.exit_code}: {result.stderr}")
print(f"created {ws.created}, exit {result.exit_code}, output {result.stdout.strip()}")

# 2. Write a file, then suspend the workspace and wait until the suspend has finished.
ws.files.write("/home/user/notes.txt", "hello from Python\n")
full = ws.open()
full.suspend(wait=True)
print(f"after suspend: {full.state}")

# 3. The same key, from this process or any other: the workspace wakes, and the file is still there.
again = workspace("quickstart/demo", template="default")
print(f"notes.txt: {again.files.read_text('/home/user/notes.txt').strip()}")
print(f"created {again.created}")

Run it:

python quickstart.py

Expected output:

created True, exit 0, output 42
after suspend: suspended
notes.txt: hello from Python
created False

workspace(key, template=...) (0.11.0+) makes no request; its first call creates the workspace and later calls reuse it. ws.exec() runs a string through bash -lc; a list runs as argv without a shell. full.suspend(wait=True) returns once the suspend has finished.

CLI quick start

Needs Node.js 24 or later.

npm i -g shardflux
shard login

shard login checks the key and stores nothing. Expected output (your ids differ):

Authenticated.
api           https://api.shardflux.dev
organization  <organization id>
project       <project id>
api key       <key id> (<api key id>)
tools         exec, files, pty, process, git, browser
The key comes from SHARDFLUX_API_KEY; shard stores nothing for it. To sign in to your account instead: shard auth login.

If you created the account from a terminal, shard also finds the key that shard setup saved when SHARDFLUX_API_KEY is not set; the last line then says so.

Run a command (the first one creates the workspace), write a file and suspend:

shard exec quickstart/cli --template default -- python3 -c 'print(40 + 2)'
echo 'hello from the CLI' | shard files write quickstart/cli /home/user/notes.txt
shard ws suspend quickstart/cli --wait

Expected output:

created workspace quickstart/cli (template default)
42
wrote 19 bytes to /home/user/notes.txt (sha256 <hash>)
Suspending quickstart/cli (<workspace id>): operation <operation id> suspend succeeded

shard exec <key> --template <slug> (0.10.0+) creates the workspace on first use and exits with the command's own exit code; -- separates the command from shard's options. ws is short for workspaces. Without --wait, lifecycle commands return as soon as the operation is requested.

Check that the workspace persisted

Read the file back. shard files read reads a suspended workspace's files from its disk, so the workspace stays suspended and uses no compute:

shard files read quickstart/cli /home/user/notes.txt
shard ws get quickstart/cli

hello from the CLI
id           <workspace id>
key          quickstart/cli
state        suspended (desired suspended)
...

shard ws resume quickstart/cli, or any command that runs in it (shard exec), wakes it with its memory and processes. See Read a suspended workspace without waking it.

The same works for the workspace the SDK programs used: shard files read quickstart/demo /home/user/notes.txt. Running either program again prints the same lines, because opening a key never resets its workspace.

What these steps verified is the file. A suspend also keeps memory and running processes; see What survives each transition.

Reach a port

Any TCP port of a workspace gets its own private HTTPS URL, and a request to it wakes the workspace. Start a server in the background, expose its port and open a signed link in your browser:

import { workspace } from '@shardflux/sdk';

const full = await workspace('quickstart/demo', { template: 'default' }).open();
await full.cell().exec.start({ argv: ['python3', '-m', 'http.server', '3000', '--bind', '0.0.0.0'] });
await full.ports.expose(3000);
const { url } = await full.ports.link(3000, { ttlSeconds: 3600 });
console.log(url); // a signed link to https://3000-<id>.shardflux.app

from shardflux import workspace

full = workspace("quickstart/demo", template="default").open()
full.cell().exec_start({"argv": ["python3", "-m", "http.server", "3000", "--bind", "0.0.0.0"]})
full.ports.expose(3000)
print(full.ports.link(3000, ttl_seconds=3600).url)

shard ws exec-start quickstart/cli --session-id web --timeout 1h -- python3 -m http.server 3000 --bind 0.0.0.0
shard ws port expose quickstart/cli 3000
shard ws port link quickstart/cli 3000

The link sets a cookie for that port only and lasts an hour here. Your own code calls the port with a port token, and webhooks and OAuth providers reach it on its callback URL. See Reach a port in a workspace.

Clean up

A suspended workspace uses no compute, but its disk still counts toward your plan's retained storage. Delete the workspaces when you are done. Deleting cannot be undone. Once deletion finishes, the key can create a new workspace with a new ID and disk:

shard ws delete quickstart/demo --yes
shard ws delete quickstart/cli --yes

Packages

Install the client you build with. Each name is the current release.

Next steps

• Workspaces: keys, projects, API keys and tool tokens, sessions, sharing a workspace.
• Lifecycle: suspend, resume, fork and what survives each.
• Give your agent workspace tools with Anthropic, OpenAI and other model providers.
• Build a template so every customer's workspace starts with your tools installed.
• Test your integration against Shardflux before you ship.