Connect a machine

Connecting a BYO machine is three moves: create the machine record, run a daemon on the computer, and grant the machine to the projects that should use it. The dashboard’s Connect a machine dialog, the CLI’s omnara machines create-local, and the API’s connect endpoint each do the first two in one step, and can attach project grants at the same time.

Create the machine record

A machine starts as a record in the control plane — the daemon attaches to it later using a machine token. The token is shown only once, so save the complete value and treat it as opaque.

Dashboard
CLI
API

With All projects selected in the project switcher, open Machines and click Connect machine. In the Connect a machine dialog, set the machine name — this is what agent configs reference as machine_name, so pick something stable — and optionally pick projects under Share with. Click Connect machine; the next screen shows the machine token alongside the install command for the daemon install step below.

To connect the computer you are sitting at, one command creates the machine, mints its token, and runs the installer locally:

npx omnara machines create-local --display-name build-server-1 --project-ids "$PROJ"

It refuses to run if ~/.omnarad (or $OMNARA_HOME) already holds a daemon install; run omnarad uninstall first to connect the computer as a new machine. If the installer fails after the machine was created, the command prints the token and the install command so you can finish by hand.To connect a different computer, create the machine from anywhere and carry the output over:

npx omnara machines create --display-name build-server-1 --project-ids "$PROJ" --json

The JSON output includes the one-time token plus an install_command to run on the target machine. Pass --token-name to label the daemon token (it defaults to daemon), and --cwd, --env, or --secret-env to set execution defaults.

The examples assume the client, $ORG/orgID, and $PROJ/projectID setup from the quickstart.

npx omnara machines create \
  --display-name build-server-1 \
  --description "Bare-metal builder in the office rack" \
  --cwd /srv/repo \
  --env '{"CI": "true"}' \
  --secret-env '{"GITHUB_TOKEN": "sec_7jehcyd5n6a2bfgik7mv4qtrwz"}' \
  --project-ids "$PROJ" \
  --json

curl "$OMNARA_API/orgs/$ORG/machines/connect" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "build-server-1",
    "description": "Bare-metal builder in the office rack",
    "cwd": "/srv/repo",
    "env": { "CI": "true" },
    "secret_env": { "GITHUB_TOKEN": "sec_7jehcyd5n6a2bfgik7mv4qtrwz" },
    "project_ids": ["'"$PROJ"'"]
  }'

const connection = await sdk.connectByoMachine({
  client,
  path: { orgID },
  body: {
    display_name: 'build-server-1',
    description: 'Bare-metal builder in the office rack',
    cwd: '/srv/repo',
    env: { CI: 'true' },
    secret_env: { GITHUB_TOKEN: 'sec_7jehcyd5n6a2bfgik7mv4qtrwz' },
    project_ids: [projectID],
  },
})
const machineID = connection.data.machine.id
const daemonToken = connection.data.token

{
  "machine": {
    "id": "mch_5n6a2bfgik7mv4qtrwz3jehcyd",
    "org_id": "org_k7mv4qtrwz3jehcyd5n6a2bfgi",
    "source_kind": "byo",
    "display_name": "build-server-1",
    "lifecycle_state": "active",
    "connection_state": "offline",
    "cwd": "/srv/repo",
    "env": { "CI": "true" },
    "secret_env": { "GITHUB_TOKEN": "sec_7jehcyd5n6a2bfgik7mv4qtrwz" },
    "...": "..."
  },
  "token": "omnara_daemon_v1_...",
  "token_record": {
    "id": "mdt_3jehcyd5n6a2bfgik7mv4qtrwz",
    "machine_id": "mch_5n6a2bfgik7mv4qtrwz3jehcyd",
    "name": "daemon",
    "...": "..."
  },
  "project_grants": [
    {
      "id": "pmg_6a2bfgik7mv4qtrwz3jehcyd5n",
      "machine_id": "mch_5n6a2bfgik7mv4qtrwz3jehcyd",
      "source_kind": "explicit",
      "...": "..."
    }
  ]
}

The response includes the plaintext token and its metadata in token_record. Store the token now; later API responses return only its metadata. project_ids is optional; omit it to grant the machine later. To create a record without a token, use the create machine endpoint instead and mint tokens separately:

curl -X POST "$OMNARA_API/orgs/$ORG/machines/mch_5n6a2bfgik7mv4qtrwz3jehcyd/daemon-tokens" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "build-server-1"}'

const daemonToken = await sdk.createByoMachineDaemonToken({
  client,
  path: { orgID, machineID: 'mch_5n6a2bfgik7mv4qtrwz3jehcyd' },
  body: { name: 'build-server-1' },
})

display_name is what agent configs reference as machine_name, so pick something stable. cwd, env, and secret_env are execution defaults for every process on this machine; secret_env injects secret values by sec_… reference at process launch, so credentials never sit in the machine record.

Install the daemon

omnara machines create-local runs this step for you. Otherwise, on the target computer, run the installer and paste the machine token when prompted:

curl -fsSL https://api.omnara.com/install/omnarad.sh | sh

The installer supports macOS and Linux on amd64 and arm64. It installs omnarad under ~/.omnarad and registers it as a user service using systemd on Linux or launchd on macOS. When no launchd or systemd user service manager is available, omnarad runs in the foreground instead; press Ctrl-C to stop it and run omnarad start to launch it again. The daemon connects outbound and updates itself. Manage it with omnarad start|stop|restart|status, or remove it with omnarad uninstall. Once the daemon connects, the machine appears online.

Grant the machine to a project

Machines are org-level; a project’s agents can only target machines granted to that project.

Dashboard
API

If you didn’t share the machine while connecting it, select All projects in the project switcher, find its row under Machines, click Share with project, and select the project.From a project, open its Machines page and click Share machines. The page’s Shared machines table lists existing shares; click Stop sharing to revoke one.

If you didn’t pass project_ids while connecting the machine, grant it afterwards:

npx omnara grant machines add --machine-id mch_5n6a2bfgik7mv4qtrwz3jehcyd --json

curl "$OMNARA_API/orgs/$ORG/projects/$PROJ/machine-grants" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"machine_id": "mch_5n6a2bfgik7mv4qtrwz3jehcyd"}'

await sdk.createProjectMachineGrant({
  client,
  path: { orgID, projectID },
  body: { machine_id: 'mch_5n6a2bfgik7mv4qtrwz3jehcyd' },
})

{
  "grant": {
    "id": "pmg_6a2bfgik7mv4qtrwz3jehcyd5n",
    "machine_id": "mch_5n6a2bfgik7mv4qtrwz3jehcyd",
    "source_kind": "explicit",
    "...": "..."
  },
  "...": "..."
}

List the project’s explicit machine grants with omnara grant machines list or the list endpoint, and revoke one by grant ID with omnara grant machines delete {grant-id} or the delete endpoint.Revoking the grant stops that project’s work on the machine but leaves the machine itself untouched. Grants created through a pool grant are managed through the pool and cannot be revoked individually.

With the grant in place, configs in that project can reference the machine:

machine_sources:
  - machine_name: build-server-1
    cwd: /srv/repo

Manage a machine

The dashboard’s Machines page (with All projects selected in the project switcher) shows every machine you can access. omnara machines list and the org API provide the same view and explain whether access comes from your org role, having created the machine, or a project grant. The project API lists only machines that project’s agents can use. You can update cwd, env, and secret_env with omnara machines update {machine-id} or through the API; machine names cannot be changed. Machine tokens can be created, listed, and revoked through the API. Deleting a BYO machine disconnects its daemon, revokes its tokens, removes its grants, and releases its agent bindings. In the dashboard, open the machine’s row menu and click Delete; in the CLI, run omnara machines delete {machine-id}.

Full schema and playground: Connect a BYO machine · Create machine · List visible machines · Daemon tokens · Machine grants.

Get started

Examples

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Connect a machine

Create the machine record

Install the daemon

Grant the machine to a project

Manage a machine

​Create the machine record

​Install the daemon

​Grant the machine to a project

​Manage a machine

Create the machine record

Install the daemon

Grant the machine to a project

Manage a machine