Managed: Direct backend

Run the oz-agent-worker daemon with the Direct backend — tasks execute directly on the worker host without Docker or Kubernetes. Oz still orchestrates runs end to end (Slack, Linear, schedules, API, oz agent run-cloud); the worker just runs the agent in a per-task workspace on its own filesystem.

Note

This page covers the managed architecture with the Direct backend. For container-based task isolation, see Managed: Docker or Managed: Kubernetes. For invocation-driven use cases, see Unmanaged.

When to use the Direct backend

• Neither Docker nor Kubernetes is available on the worker host.
• Tasks need direct access to host resources that are hard to expose through a container.
• You want managed orchestration (triggering from Slack, Linear, schedules, API) without the operational overhead of a container runtime.

Caution

The Direct backend does not provide per-task container isolation. Each task runs in an isolated workspace directory, but shares the host OS and kernel. Evaluate whether this fits your security requirements before using it in production.

---

How it works

1. The worker creates a per-task workspace directory under workspace_root.
2. If a setup_command is configured, it runs before the task with environment variables pointing to the workspace.
3. The oz CLI runs the agent task inside the workspace directory.
4. After the task completes, the optional teardown_command runs and the workspace is cleaned up.

---

Prerequisites

• Enterprise plan with self-hosting enabled — Contact sales if self-hosting is not yet enabled for your team.
• A worker host with write access to workspace_root (defaults to /var/lib/oz/workspaces).
• The Oz CLI installed and available in PATH on the worker host (or specify oz_path in the config file). See Installing the CLI.
• An agent API key — Create one in the Oz web app so the worker can authenticate to Oz. You can bind the key to any cloud agent — that choice doesn’t restrict which agents can run on the worker. See API Keys for the full creation flow.

---

Setup

1. Set your API key

Export the API key so the worker can authenticate to Oz:

export WARP_API_KEY="your_agent_api_key"

2. Start the worker with the Direct backend

Pass --backend direct:

oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" --backend direct

Or with a config file:

worker_id: "my-worker"
backend:
  direct:
    workspace_root: "/var/lib/oz/workspaces"

Expected outcome: The worker connects to Oz and begins listening for tasks. Each assigned task runs in a freshly-created subdirectory of workspace_root.

---

Workspace model

Each task gets its own directory under workspace_root. The default is /var/lib/oz/workspaces; override it with the workspace_root config option shown above.

After the task completes, the workspace is deleted (unless --no-cleanup is set, which keeps the directory around for debugging).

---

Setup and teardown commands

The setup_command runs before each task and receives the following environment variables:

• OZ_WORKSPACE_ROOT — The workspace directory for the task.
• OZ_RUN_ID — The unique task ID.
• OZ_ENVIRONMENT_FILE — Path to a file where the setup script can write additional KEY=VALUE environment variables to inject into the task.
• OZ_WORKER_BACKEND — Always set to direct.

The teardown_command runs after each task and receives OZ_WORKSPACE_ROOT, OZ_RUN_ID, and OZ_WORKER_BACKEND.

Use the setup command to clone repos, install dependencies, or write task-specific env vars into OZ_ENVIRONMENT_FILE. Use the teardown command for cleanup or reporting.

---

Environment variables for Direct tasks

Note

The Direct backend starts tasks with a minimal environment (only HOME, TMPDIR, and PATH from the host) to avoid leaking sensitive worker credentials like WARP_API_KEY into tasks. Add variables explicitly via environment in the config file or -e flags on the worker CLI.

Config file example:

worker_id: "direct-worker"
max_concurrent_tasks: 2
backend:
  direct:
    workspace_root: "/var/lib/oz/workspaces"
    oz_path: "/usr/local/bin/oz"
    setup_command: "/opt/scripts/setup.sh"
    teardown_command: "/opt/scripts/teardown.sh"
    environment:
      - name: MY_VAR
        value: "hello"

---

Related pages

• Self-hosted worker reference — Full config schema for the Direct backend.
• Self-hosting overview — Managed vs unmanaged and the backend decision guide.
• Routing runs to self-hosted workers — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI.
• Security and networking — Data boundaries and security considerations for the Direct backend.
• Troubleshooting — Common Direct-backend issues.