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

# Connect To Machine

> Reconnect to existing machines with CLI commands, PTY sessions, SSH, and preview URLs.

Nullspace does not require a long-lived local tunnel before you can work with a
machine. Most CLI commands connect directly to the hosted API using a machine
ID.

## Inspect A Machine

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine get mch_123
nullspace machine metrics mch_123 --json
```

If you do not know the ID, list machines first:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine list --state running
```

Commands that operate on a paused auto-resumable machine may wake it before
continuing. Use `nullspace machine get mch_123` for inspection when you only need
metadata and do not want to depend on command execution.

## Run A Command

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine exec mch_123 --shell "uname -a && pwd"
```

For long-running commands, start a background process and reconnect through the
process commands:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine exec mch_123 --shell "python3 -m http.server 8080" --background
nullspace machine process list mch_123
nullspace machine process logs mch_123 1234
nullspace machine process attach mch_123 1234
```

## Open An Interactive Terminal

Use PTY sessions when you need an interactive shell:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine pty create mch_123 --cols 120 --rows 30
nullspace machine pty list mch_123
nullspace machine pty connect mch_123 --session-id ses_123
```

Use the `session_id` from `machine pty create` with `--session-id`. Numeric
`pid` reconnect remains available for legacy scripts.

You can resize or kill a session later:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine pty resize mch_123 ses_123 --cols 160 --rows 40
nullspace machine pty kill mch_123 ses_123
```

## Expose A Service

Start a service inside the machine, then request a signed URL:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine exec mch_123 --shell "cd /workspace && python3 -m http.server 8080" --background
nullspace machine url mch_123 8080
nullspace machine url mch_123 8080 --websocket
```

For host-level connection metadata:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine host mch_123 8080 --json
```

## SSH

Use the SSH guide when your tool expects an OpenSSH transport instead of CLI
commands:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace ssh mch_123
nullspace ssh mch_123 -- python --version
nullspace machine ssh-access mch_123 --print-command
```

See [SSH Access](../access/ssh) for certificate-backed relay access and the
legacy signed WebSocket proxy fallback.

## Related

* [Execute Commands In Machine](./execute-commands)
* [PTY Sessions](../access/pty)
* [Preview URLs](../networking/preview-urls)
* [WebSockets](../networking/websockets)