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

# Agent37

> Always-on Linux computers for agents, running in seconds from any image and billed by the minute

[Agent37](https://www.agent37.com) gives each machine its own always-on Linux sandbox with a persistent disk, created in a few seconds. Connect your Agent37 workspace with a custom pool.

## Why Agent37

* **Omnara's tools, baked in.** `agent37-omnara` is Ubuntu 24.04 with the same development tools as Omnara's [default machine environment](https://docs.omnara.com/machines/pools.md#default-machine-environment), so a pool only needs an API key. For your own stack, turn a public registry image into a template with one API call, or build one from a Dockerfile in Agent37's cloud with no local Docker.
* **A URL for every port.** A dev server or app an agent starts gets its own HTTPS address at `https://{instance}-{port}.agent37.app`, and a [signed link](https://www.agent37.com/docs/agents-api/urls) opens it in your browser.
* **SSH into any machine.** Add your public key once, then use `ssh`, `scp`, or VS Code Remote to watch an agent work or pick up where it left off. See [SSH](https://www.agent37.com/docs/agents-api/ssh).
* **Pay for the minutes you use.** Machines bill by the minute from a prepaid balance, and auto top-up refills it before it runs out.

## Set up an Agent37 pool

**1. Create an API key**

In the [Agent37 dashboard](https://www.agent37.com/dashboard/cloud/api-keys), create an API key and store it as an org-owned [secret](https://docs.omnara.com/organization/secrets.md) in Omnara. Machines run and bill in that key's workspace, so [add funds](https://www.agent37.com/docs/agents-api/billing) before you create the pool: a workspace that has never been topped up runs one small machine.

**2. Choose a template**

Leave the template empty to use `agent37-omnara`: Ubuntu 24.04 as root with the [default machine environment](https://docs.omnara.com/machines/pools.md#default-machine-environment) preinstalled: Python, Node.js, Go, PostgreSQL, Redis, `gh`, `rg`, PDF tools, and Playwright with headless Chromium.

For your own tools, use a template in your Agent37 workspace. Register a public `linux/amd64` image that meets the [custom image requirements](https://docs.omnara.com/machines/providers/overview.md#custom-image-requirements) with one call:

```bash theme={null}
curl -X POST https://api.agent37.com/v1/templates \
  -H "Authorization: Bearer $AGENT37_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "omnara-machine",
    "image_ref": "docker.io/library/buildpack-deps:24.04-curl",
    "entrypoint": ["/bin/sh", "-c", "trap \"exit 0\" TERM; while :; do sleep 3600 & wait $!; done"]
  }'
```

* Omnara starts the daemon with a command on the running machine, so the image's main process only has to keep running. The `entrypoint` above does that for an image whose own command exits, and cleans up the processes agents leave behind.
* Agents run commands as the image's default user, so pick an image that runs as root if they should install packages.
* Machines are containers, so pick an image that doesn't need Docker or systemd.
* To build one from a Dockerfile, use `npx agent37 templates build`. See [Agent37 templates](https://www.agent37.com/docs/agents-api/templates).

**3. Create the pool**

On the **Machines** page, click **New pool** and choose **Agent37**. Enter the credential, the template (or leave it empty), the CPU and memory, and capacity limits.

Each machine is 2 vCPU with 4 GB of memory, or 4 vCPU with 8, 16, or 32 GB. Only environment variables whose names use letters, digits, and underscores, and don't start with a digit, reach the machine.

To use the API instead, call [Create a pool](https://docs.omnara.com/machines/pools.md#create-a-pool) with the fields under [API fields](#api-fields).

## API fields

When you create a pool through the API, send these fields in the [Create a pool](https://docs.omnara.com/machines/pools.md#create-a-pool) request. `provider_config` applies to the whole pool, and `default_machine_provider_options` sets the options for each new machine, which project grants and agent configs can override. For example:

```jsonc theme={null}
{
  "name": "agent37-pool",
  "provider": "agent37",
  "provider_auth_secret_id": "sec_hcyd5n6a2bfgik7mv4qtrwz3je",
  "default_machine_provider_options": {
    "template": "omnara-machine" // optional
  },
  "default_machine_cpu": 2,
  "default_machine_memory_mb": 4096,
  "max_machine_cpu": 4,
  "max_machine_memory_mb": 8192,
  "max_total_cpu": 20,
  "max_total_memory_mb": 40960,
  "max_total_machines": 10
}
```

* `template` is optional. Omit it to use `agent37-omnara`, or set the name of a template in your Agent37 workspace. Add `@<revision>`, such as `omnara-machine@2`, to pin a published revision.
* CPU and memory must be one of Agent37's sizes: 2 vCPU with 4096 MB, or 4 vCPU with 8192, 16384, or 32768 MB.
* Optional: `startup_script` in `default_machine_provider_options` runs on each new machine before the daemon starts, and `allowed_templates` in `provider_config` is an [allowlist](https://docs.omnara.com/machines/providers/overview.md#allowlists).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.