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

# Bring Your Own Agent

> Run a custom agent loop with Nullspace as the isolated workspace.

Use this guide when your framework is not listed, or when you have a custom
planner/executor that needs an isolated Linux workspace.

There are two supported shapes:

* Use direct machine APIs when your application needs fine-grained command,
  file, PTY, SSH, desktop, or lifecycle control.
* Use [Agent Deployments](./deployments) when you want Nullspace to deploy a
  named job or service from a local project and operate it over time.

## Integration Shape

1. Create a machine from `base` or a custom template.
2. Pass only the credentials and configuration the agent needs through `envs`.
3. Clone or upload workspace inputs into `/workspace`.
4. Run agent steps with `machine.commands`, `machine.files`, `machine.git`, or
   framework-specific tools.
5. Collect outputs, artifacts, diffs, logs, or preview URLs.
6. Hibernate for resumable machines or destroy for one-shot tasks.

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

with Machine.create(
    template="base",
    envs={"AGENT_RUN_ID": "run_123"},
    timeout=900,
) as machine:
    machine.git.clone("https://github.com/example/project.git", "/workspace/project")
    result = machine.commands.run(
        "./your-agent --task 'inspect the project'",
        shell=True,
        cwd="/workspace/project",
        timeout=900,
    )
    print(result.stdout)
```

## When To Use Agent Deployments

Use [Agent Deployments](./deployments) when you want Nullspace to deploy a
named job or service from your local project, manage runs or service instances,
retain backing machines for debugging, and collect logs and outputs through
the deployment API. Keep using direct machine APIs when your app needs
fine-grained control over every machine command, upload, download, PTY session,
SSH session, desktop interaction, or lifecycle action.

## Template Strategy

* Use `base` for one-off command and file tasks.
* Build a custom template when your agent repeatedly installs the same tools,
  package managers, browsers, or language runtimes.
* Use [start-ready commands](../templates/start-ready) for services the agent
  expects to be available immediately.

## Cleanup Strategy

* Destroy short-lived machines with `machine.kill()` or a context manager.
* Use `on_timeout="pause", auto_resume=True` for per-user workspaces.
* Use [Fork](../machines/fork) to test multiple plans from a shared warm
  setup.

## State And Sessions

Nullspace run IDs are not conversation session IDs. Framework session, thread,
checkpoint, or flow state stays app-owned. Use volumes, retained machines,
hibernate/auto-resume, or an external database for durable conversation state,
repo state, generated artifacts, or framework checkpoint storage.

## Related

* [Agents overview](./overview)
* [Templates](../templates/overview)
* [Fork](../machines/fork)