Shell - Upstash Documentation

Every box has a full Linux shell and runs on Debian by default. You can access that shell either through the SDK or directly over SSH.

SSH

Connect to a box with:

ssh <box-id>@us-east-1.box.upstash.com

When prompted for a password, use your Box API key. For example:

ssh current-wasp-05510@us-east-1.box.upstash.com

You can also copy this command from the SSH button on the box details page in the Upstash Console.

SSH keys

Instead of the password, you can log in with an SSH key. A key you add works for all boxes in your account or team.

Create a key pair, if you don’t have one:

mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -f ~/.ssh/upstash_box

In the Upstash Console, go to Box → Settings → SSH Keys, click New SSH Key, and paste the contents of ~/.ssh/upstash_box.pub.

Connect with the private key:

ssh -i ~/.ssh/upstash_box <box-id>@us-east-1.box.upstash.com

If your key is one SSH tries by default, such as ~/.ssh/id_ed25519, you can leave out -i.

You can also click Generate Key to have Upstash create the key pair. The private key is shown only once and isn’t stored, so save it right away.

Accepted key types are ed25519, ECDSA, their security-key (sk-) variants, and RSA keys of at least 2048 bits. An account can have up to 20 keys.

API

Run a shell command

A shell command resolves when the command finishes and gives you back the result and status.

const run = await box.exec.command("echo hello")

console.log(run.result) // "hello"
console.log(run.status) // "completed"

run = box.exec.command("echo hello")

print(run.result)  # "hello"
print(run.status)  # "completed"

If you need additional system tools, install them with Debian’s package manager inside the box.

await box.exec.command("sudo apt-get install <package>")

box.exec.command("sudo apt-get install <package>")

Run a code snippet

You can execute code inside of a box:

const run = await box.exec.code({
  code: "console.log('hello')",
  lang: "js",
  timeout: 10_000,
})

console.log(run.output) // "hello"
console.log(run.exit_code) // "0"

run = box.exec.code(code="print('hello')", lang="python", timeout=10_000)

print(run.result)     # "hello"
print(run.exit_code)  # 0

Check exit status

If the command fails, the run status will be "failed" and its result contains the stderr output.

const run = await box.exec.command("node -e 'process.exit(1)'")

console.log(run.status) // "failed"

run = box.exec.command("node -e 'process.exit(1)'")

print(run.status)  # "failed"

Chain commands

Pass a full shell expression. Pipes, redirects, and chained commands all work as expected.

const run = await box.exec.command("cd /work && npm install && npm test")

console.log(run.result)

run = box.exec.command("cd /work && npm install && npm test")

print(run.result)

Hold a command open

exec.command runs a command to completion. When you need to write to stdin, drive an interactive program through a terminal, or signal a process while it runs, start a live session instead.

const session = await box.exec.session({ argv: ["sort"] })
session.write("banana\napple\n")
session.endStdin()

await session.wait()

session = box.exec.session(argv=["sort"])
session.write("banana\napple\n")
session.end_stdin()

session.wait(30)

Cancel a long-running command

You can cancel a run to abort it. The status becomes "cancelled".

const run = await box.exec.command("sleep 10")
await run.cancel()

console.log(run.status) // "cancelled"

run = box.exec.command("sleep 10")
run.cancel()

print(run.status)  # "cancelled"

Retrieve logs

After a command finishes, call logs() to get the full timestamped output for debugging or auditing.

const run = await box.exec.command("npm test")
const logs = await run.logs()

console.log(logs)
// [
//   { timestamp: "2026-02-23T...", level: "info", message: "PASS src/auth.test.ts" },
//   { timestamp: "2026-02-23T...", level: "info", message: "Tests: 12 passed, 12 total" },
// ]

run = box.exec.command("npm test")
logs = run.logs()

print(logs)
# [
#   RunLog(timestamp="2026-02-23T...", level="info", message="PASS src/auth.test.ts"),
#   RunLog(timestamp="2026-02-23T...", level="info", message="Tests: 12 passed, 12 total"),
# ]

Examples

Install dependencies before a run

Set up the environment with box.exec.command(), then hand off to the agent.

import { Agent, Box } from "@upstash/box"

const box = await Box.create({
  runtime: "node",
  agent: { harness: Agent.ClaudeCode, model: "anthropic/claude-opus-4-6", apiKey: process.env.ANTHROPIC_API_KEY },
  git: { token: process.env.GITHUB_TOKEN },
})

await box.git.clone({ repo: "github.com/your-org/your-api" })
await box.exec.command("npm install")

await box.agent.run({
  prompt: "Run the test suite and fix any failing tests",
})

import os
from upstash_box import Box, Agent

box = Box.create(
    runtime="node",
    agent={"harness": Agent.CLAUDE_CODE, "model": "anthropic/claude-opus-4-6", "api_key": os.environ["ANTHROPIC_API_KEY"]},
    git={"token": os.environ["GITHUB_TOKEN"]},
)

box.git.clone(repo="github.com/your-org/your-api")
box.exec.command("npm install")

box.agent.run(prompt="Run the test suite and fix any failing tests")

Run a build and extract artifacts

Execute a build command, then download the output.

import { Agent, Box } from "@upstash/box"

const box = await Box.create({ runtime: "node" })

await box.files.upload([
  { path: "./src", destination: "/work/src" },
  { path: "./package.json", destination: "/work/package.json" },
])

await box.exec.command("cd /work && npm install && npm run build")
await box.files.download({ folder: "/work/dist" })
await box.delete()

from upstash_box import Box

box = Box.create(runtime="node")

box.files.upload([
    {"path": "./src", "destination": "/work/src"},
    {"path": "./package.json", "destination": "/work/package.json"},
])

box.exec.command("cd /work && npm install && npm run build")
box.files.download(folder="/work/dist")
box.delete()

Health-check before handing off

Verify the environment is usable before starting a longer agent task.

import { Agent, Box } from "@upstash/box"

const box = await Box.create({
  runtime: "python",
  agent: { harness: Agent.ClaudeCode, model: "anthropic/claude-opus-4-6", apiKey: process.env.ANTHROPIC_API_KEY },
})

const check = await box.exec.command("python3 --version && pip list")
console.log(check.result)

await box.agent.run({
  prompt: "Write a data pipeline that reads /work/raw.csv, cleans it, and saves /work/clean.parquet",
})

import os
from upstash_box import Box, Agent

box = Box.create(
    runtime="python",
    agent={"harness": Agent.CLAUDE_CODE, "model": "anthropic/claude-opus-4-6", "api_key": os.environ["ANTHROPIC_API_KEY"]},
)

check = box.exec.command("python3 --version && pip list")
print(check.result)

box.agent.run(prompt="Write a data pipeline that reads /work/raw.csv, cleans it, and saves /work/clean.parquet")

​SSH

​SSH keys

​API

​Run a shell command

​Run a code snippet

​Check exit status

​Chain commands

​Hold a command open

​Cancel a long-running command

​Retrieve logs

​Examples

​Install dependencies before a run

​Run a build and extract artifacts

​Health-check before handing off

SSH

SSH keys

API

Run a shell command

Run a code snippet

Check exit status

Chain commands

Hold a command open

Cancel a long-running command

Retrieve logs

Examples

Install dependencies before a run

Run a build and extract artifacts

Health-check before handing off