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

# Connect a machine

> Register your own machine and grant it to projects

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**

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.

**CLI**

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

```bash theme={null}
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:

```bash theme={null}
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.

**API**

The examples assume the client, `$ORG`/`orgID`, and `$PROJ`/`projectID` setup from the [quickstart](/quickstart).

```bash CLI theme={null}
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
```

```bash REST theme={null}
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"'"]
  }'
```

```typescript SDK theme={null}
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
```

```json theme={null}
{
  "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](/api-reference/endpoints/machines/create-machine) endpoint instead and mint tokens separately:

```bash REST theme={null}
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"}'
```

```typescript SDK theme={null}
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](/organization/secrets) 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:

```sh theme={null}
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**

If you didn't share the machine while connecting it, select **All projects** in the project switcher, open **Machines**, and click **BYO Machines**. Open the machine's row actions, click **Share with project**, and select the project.

From a project, open its **Machines** page and click **Share machines**. To see existing shares, click **BYO Machines**; open a row's actions and click **Stop sharing** to revoke one.

**API**

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

```bash CLI theme={null}
npx omnara grant machines add --machine-id mch_5n6a2bfgik7mv4qtrwz3jehcyd --json
```

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

```typescript SDK theme={null}
await sdk.createProjectMachineGrant({
  client,
  path: { orgID, projectID },
  body: { machine_id: 'mch_5n6a2bfgik7mv4qtrwz3jehcyd' },
})
```

```json theme={null}
{
  "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](/api-reference/endpoints/machines/list-project-machine-grants), 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](/machines/pools) are managed through the pool and cannot be revoked individually.

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

```yaml theme={null}
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}`.

> [!NOTE]
>
> Full schema and playground: [Connect a BYO machine](/api-reference/endpoints/machines/connect-a-byo-machine) · [Create machine](/api-reference/endpoints/machines/create-machine) · [List visible machines](/api-reference/endpoints/machines/list-visible-machines) · [Daemon tokens](/api-reference/endpoints/machines/list-byo-machine-daemon-tokens) · [Machine grants](/api-reference/endpoints/machines/create-project-machine-grant).


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