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

Tip

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 ~/.sshssh-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.

Note

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 osfrom upstash_box import Box, Agentbox = 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 Boxbox = 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 osfrom upstash_box import Box, Agentbox = 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")