Bring Your Own Agent

• Use direct machine APIs when your application needs fine-grained command, file, PTY, SSH, desktop, or lifecycle control.
• Use Agent 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.

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

​

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 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 to test multiple plans from a shared warm setup.

​

State And Sessions

​

Related

• Agents overview
• Templates
• Fork