SSH Access - ascii

Boxes accept standard SSH connections. The Box CLI handles the usual setup for you, including the SSH key it uses to connect.

Connect with the CLI

Use box ssh from your local machine for an interactive shell. For non-interactive commands, use the same Box work access through the SDK, API, curl, or CLI:

box ssh bx_f7k2q9hd
box ssh bx_f7k2q9hd "cd /home/user/my-repo && npm test"
box ssh bx_f7k2q9hd -- bash -lc "cd /home/user/my-repo && npm test"
box ssh bx_f7k2q9hd -- bash -s < ./setup.sh

curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/commands" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"npm test","cwd":"my-repo","timeoutSeconds":60}'

const result = await box.command({
  boxId: "bx_f7k2q9hd",
  commandRequest: { command: "npm test", cwd: "my-repo", timeoutSeconds: 60 },
});
console.log(result.stdout);

from ascii_box_sdk.models.command_request import CommandRequest

result = box.command(
    "bx_f7k2q9hd",
    CommandRequest(command="npm test", cwd="my-repo", timeout_seconds=60),
)
print(result.stdout)

The CLI manages its SSH key at:

~/.ssh/ascii_box_ed25519

If the key is missing, the CLI creates or refreshes it and authorizes it on the box before connecting.

SSH is available only when the box’s machine is running. If the box is archived or still provisioning, resume it or wait until it is ready. In the first seconds of a resume, SSH may answer with a retryable box_restoring error; retry a moment later.

Use another SSH client

If you want to connect from an external SSH client, first authorize a public key and inspect the Box for its IP address:

box info bx_f7k2q9hd
ssh -i ~/.ssh/ascii_box_ed25519 user@<box-ip>

curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/sshkey" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"ssh-ed25519 AAAAC3Nza... you@example.com"}'

curl -sS "$BOX_API_BASE/boxes/bx_f7k2q9hd" \
  -H "Authorization: Bearer $BOX_API_KEY"

await box.sshKey({
  boxId: "bx_f7k2q9hd",
  sshKeyRequest: { key: "ssh-ed25519 AAAAC3Nza... you@example.com" },
});

const info = await box.get({ boxId: "bx_f7k2q9hd" });
console.log(info.box.ip);

from ascii_box_sdk.models.ssh_key_request import SshKeyRequest

box.ssh_key("bx_f7k2q9hd", SshKeyRequest(key="ssh-ed25519 AAAAC3Nza... you@example.com"))
info = box.get("bx_f7k2q9hd")
print(info.box.ip)

Copy files

Use box scp with the box ID as the remote host, or use file/artifact API calls when you are building an integration:

box scp ./local-file.txt bx_f7k2q9hd:/home/user/
box scp bx_f7k2q9hd:/home/user/output.zip ./output.zip

curl -sS -X PUT "$BOX_API_BASE/boxes/bx_f7k2q9hd/files" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"notes/input.txt","content":"hello\n","encoding":"utf8"}'

curl -L -o output.zip "$BOX_API_BASE/boxes/bx_f7k2q9hd/artifacts?path=output.zip" \
  -H "Authorization: Bearer $BOX_API_KEY"

await box.writeFile({
  boxId: "bx_f7k2q9hd",
  fileWriteRequest: { path: "notes/input.txt", content: "hello\n", encoding: "utf8" },
});

const artifact = await box.artifact({ boxId: "bx_f7k2q9hd", path: "output.zip" });

from ascii_box_sdk.models.file_write_request import FileWriteRequest

box.write_file("bx_f7k2q9hd", FileWriteRequest(
    path="notes/input.txt",
    content="hello\n",
    encoding="utf8",
))
artifact = box.artifact("bx_f7k2q9hd", "output.zip")

File read/write paths may be relative (resolved from the box work directory, /home/user) or absolute; an absolute path must resolve under /home/user or /tmp, anything else is refused with a 400 invalid_path error naming the allowed roots. See CLI Reference for all scp options.

​Connect with the CLI

​Use another SSH client

​Copy files

​Related

Connect with the CLI

Use another SSH client

Copy files

Related