> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ascii.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SSH Access

> Connect to a Box over SSH from your terminal or external tools.

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:

<CodeGroup>
  ```bash CLI theme={null}
  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
  ```

  ```bash curl theme={null}
  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}'
  ```

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

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

The CLI manages its SSH key at:

```text theme={null}
~/.ssh/ascii_box_ed25519
```

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

<Note>
  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.
</Note>

## 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:

<CodeGroup>
  ```bash CLI theme={null}
  box info bx_f7k2q9hd
  ssh -i ~/.ssh/ascii_box_ed25519 user@<box-ip>
  ```

  ```bash curl theme={null}
  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"
  ```

  ```ts TypeScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```bash CLI theme={null}
  box scp ./local-file.txt bx_f7k2q9hd:/home/user/
  box scp bx_f7k2q9hd:/home/user/output.zip ./output.zip
  ```

  ```bash curl theme={null}
  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"
  ```

  ```ts TypeScript theme={null}
  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" });
  ```

  ```python Python theme={null}
  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")
  ```
</CodeGroup>

See [CLI Reference](/box/cli-reference#box-scp) for all `scp` options.

## Related

* [Secrets & Setup](/box/secrets)
* [Long-Running Tasks](/box/long-running-tasks)
* [Desktop Streaming](/box/desktop-streaming)
* [Hosting](/box/hosting)