shardfluxDocs Sign up

Quickstart

Create a Shardflux account and API key, then open a persistent workspace, run a command and check that a file survives suspend.

What you will do

  1. Sign up and create a project API key.
  2. Open a workspace by key, run python3 -c "print(40 + 2)" in it and check the result.
  3. Write a file, suspend the workspace, open the same key again and read the file back.

Pick one of the three paths: TypeScript, Python or the CLI. Each is a complete program or command sequence with the output to expect.

Sign up and create an API key

  1. Sign up at https://app.shardflux.dev/signup and confirm your email address.
  2. Create your organization (it starts on the Free plan) and your first project.
  3. Open API keys in the console and choose Create API key. Give it a name, such as the service that will use it, and keep the workspace tools checked ("What code with this key can do in a workspace"). Opening and running workspaces needs at least one tool; organization owners and admins can create keys with tools.
  4. Copy the key. It looks like sfk_<key id>_<secret> and is shown once. If you lose it, revoke it and create a new one.

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

Shell
export SHARDFLUX_API_KEY=sfk_...

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

Or from a terminal

The shard CLI (0.5.0+) does the same steps without a browser, which is how a coding agent without an account gets one. The password is read from standard input, never from an argument:

Shell
printf '%s\n' "$PASSWORD" | npx @shardflux/cli@latest auth register --email you@example.com
npx @shardflux/cli@latest auth verify-email '<link from the verification email>'
printf '%s\n' "$PASSWORD" | npx @shardflux/cli@latest auth login --email you@example.com
npx @shardflux/cli@latest setup
eval "$(npx @shardflux/cli@latest env)"

auth verify-email takes the link from the verification email (quoted), so a person opens that email or hands the link over. setup creates the organization (on the Free plan), a project and an API key with every workspace tool, and saves the key in ~/.config/shardflux/credentials.json. env prints it as export SHARDFLUX_API_KEY=..., so the eval line sets it for the examples below. See Accounts and sign-in.

TypeScript quick start

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

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

Save this as quickstart.ts:

TypeScript
import { Shardflux } from '@shardflux/sdk';

const cloud = new Shardflux({ apiKey: process.env.SHARDFLUX_API_KEY! });
const open = () => cloud.workspaces.open({ key: 'quickstart/demo', template: 'python-node-browser' });

// 1. Open the workspace (created on first use) and run a command. Check that it worked.
const workspace = await open();
console.log(`opened ${workspace.key}: ${workspace.state}`);
const run = await workspace.cell().exec.run(['python3', '-c', 'print(40 + 2)']);
if (run.exitCode !== 0) throw new Error(`python3 exited ${run.exitCode}: ${run.stderr}`);
console.log(`exit ${run.exitCode}, output ${run.stdout.trim()}`);

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

// 3. Open the same key again: the workspace resumes, and the file is still there.
const again = await open();
console.log(`reopened: ${again.state}`);
console.log(`notes.txt: ${(await again.cell().files.readText('/home/user/notes.txt')).trim()}`);

Run it:

Shell
node quickstart.ts

Expected output:

Text
opened quickstart/demo: running
exit 0, output 42
after suspend: suspended
reopened: running
notes.txt: hello from the SDK

open() waits until the workspace is running. The first run creates the workspace, which takes longer than the runs after it. 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.

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

Save this as quickstart.py:

Python
from shardflux import Shardflux

sf = Shardflux()  # reads SHARDFLUX_API_KEY


def open_workspace():
    return sf.open(key="quickstart/demo", template="python-node-browser")


# 1. Open the workspace (created on first use) and run a command. Check that it worked.
ws = open_workspace()
print(f"opened {ws.key}: {ws.state}")
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"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")
ws.suspend(wait=True)
print(f"after suspend: {ws.state}")

# 3. Open the same key again: the workspace resumes, and the file is still there.
again = open_workspace()
print(f"reopened: {again.state}")
print(f"notes.txt: {again.files.read_text('/home/user/notes.txt').strip()}")

Run it:

Shell
python quickstart.py

Expected output:

Text
opened quickstart/demo: running
exit 0, output 42
after suspend: suspended
reopened: running
notes.txt: hello from Python

ws.exec() runs a list as argv without a shell; a string runs through bash -lc. ws.suspend(wait=True) returns once the suspend has finished.

CLI quick start

Needs Node.js 24 or later.

Shell
npm install -g @shardflux/cli
shard login

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

Text
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.

Open a workspace, run a command, write a file and suspend:

Shell
shard ws open quickstart/cli --template python-node-browser
shard ws exec quickstart/cli -- 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 (the workspace details after the first line are abbreviated):

Text
Workspace quickstart/cli (<workspace id>) is ready.
id           <workspace id>
key          quickstart/cli
state        running (desired running)
...
42
wrote 19 bytes to /home/user/notes.txt (sha256 <hash>)
Suspending quickstart/cli (<workspace id>): operation <operation id> suspend succeeded

shard ws exec exits with the command's own exit code. ws is short for workspaces, and -- separates the command from shard's options. Without --wait, lifecycle commands return as soon as the operation is requested.

Check that the workspace persisted

Read the file back. shard files read resumes the suspended workspace first:

Shell
shard files read quickstart/cli /home/user/notes.txt
shard ws get quickstart/cli
Text
hello from the CLI
id           <workspace id>
key          quickstart/cli
state        running (desired running)
...

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.

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, and a deleted workspace's key is never reused:

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

Next steps

View this page as Markdown