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

# Agent Workspace

> Clone a repository and run checks inside a machine, the way an agent would.

A common agent pattern: clone a repo into an isolated machine, inspect it, and
run checks — without touching the host machine. This example uses a public
repository; for private repos, inject credentials via `envs` at create time.

## Setup

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
uv pip install "nullspace-sdk==1.0.0"
export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
```

## Python

```python workspace_example.py theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import Machine

REPO = "https://github.com/pypa/sampleproject.git"

with Machine.create(template="base", timeout=120) as machine:
    clone = machine.commands.run(
        f"git clone --depth 1 {REPO} /workspace/repo", shell=True, timeout=90
    )
    assert clone.exit_code == 0, clone.stderr

    head = machine.commands.run(
        "git -C /workspace/repo rev-parse --short HEAD", shell=True
    )
    print("repo head:", head.stdout.strip())

    checks = machine.commands.run(
        "cd /workspace/repo && python3 -m compileall -q src && echo checks-passed",
        shell=True,
    )
    print(checks.stdout.strip())
```

## Expected output

```text theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
repo head: <short-sha>
checks-passed
```

From here an agent typically reads files (`machine.files.read`), edits them
(`machine.files.write`), re-runs tests, and [forks](./fork) the warm workspace
to try multiple approaches in parallel.

To run a *coding agent itself* inside the machine — Codex, Claude Code, Amp,
or OpenCode — see [Agent workspaces](../agents/overview).

Related: [Commands](../commands/overview) ·
[Filesystem](../filesystem)