# Aglit Computer Use

Connect your devices to Aglit so AI can work across them. Start with a laptop
or desktop, then connect phones and use compatible integrations to control
equipment such as 3D printers and robots.

## Initialize a device

### Install Aglit

**Apple silicon Mac**

```sh
curl -fsSL https://aglit.ai/install.sh | sh
```

**Windows x64, in PowerShell**

```powershell
irm -UseBasicParsing https://aglit.ai/install.ps1 | iex
```

Use the installer once per computer. It puts the `aglit` command on your
account and starts guided setup. If the terminal cannot find `aglit` after
installation, open a new terminal. Aglit checks for updates automatically
while Desktop is running.

### Set up or edit this computer

```sh
aglit init
```

Run `aglit init` to start or resume setup and edit settings such as the
computer name and AI provider. Running `aglit` opens the same flow. Before
sign-in, keep the account server for this CLI environment or enter your company’s
self-hosted HTTPS origin. Follow the prompts to grant local permissions. Aglit
installs Desktop if needed and opens it when setup finishes. An Aglit account
is optional for local use. Sign in and approve Anywhere Access on this device
to control it from another computer.

### Set up with an AI agent

Give your agent this prompt:

```text
Help me set up Aglit on this computer. Read https://aglit.ai/docs/index.md. Run aglit if it is already installed. Otherwise, use the installer for my operating system. Let me handle account sign-in, provider selection, and permission prompts. Leave the Anywhere Access setting as it is unless I ask to change it. When setup is complete, run aglit status --json and summarize what is configured.
```

## Command reference

Run the examples individually. Replace uppercase IDs and paths with your own
values. `aglit --help` shows this guide in your terminal.
`aglit server --help` shows the self-hosting section.

### Local app

```sh
aglit ui
aglit status
aglit status --json
aglit uninstall
```

- `aglit ui` opens the Desktop window.
- `aglit status` checks whether Desktop is installed and running on this
  computer. When running, it reports the computer name, Desktop version,
  sign-in, provider, permissions, and Anywhere Access state. Use `--json`
  for scripts and agents.
- `aglit uninstall` removes this installation and its local history.

### Browser

```sh
aglit browser setup
aglit browser status --json
```

Browser setup installs or connects the Chrome extension.

### Console

```sh
aglit console
aglit console --device DEVICE_ID
aglit console --employee EMPLOYEE_ID
aglit console --employee EMPLOYEE_ID --device DEVICE_ID
```

`aglit console` opens your browser with device verification using the account
signed in to Desktop. Enable Anywhere Access on this computer first.

With no flags it opens this computer. Use `--device` for an enrolled computer,
`--employee` for an employee’s default device view, or both flags for a
specific device assigned to that employee. The usual device access checks
apply to the selected target.

### Access

```sh
aglit access status --json
aglit access enable
aglit access disable
```

Anywhere Access controls whether other devices can reach this computer.
Enabling it requires sign-in and local approval.

### Desktop

```sh
aglit desktop status --json
aglit desktop setup
aglit desktop capture > screen.jpg
```

Check or grant screen-control permissions with `status` and `setup`.
`capture` writes a JPEG from the running Desktop to standard output.

### SSH

```sh
aglit ssh status
aglit ssh list
aglit ssh DEVICE_ID
aglit ssh DEVICE_ID --command "hostname"
```

Use SSH only for computers you’re authorized to access.

### Devices

```sh
aglit devices list
aglit devices list --employee EMPLOYEE_ID --json
aglit devices discover
aglit devices attached
aglit devices interfaces
aglit devices register --file device.json
aglit devices register DEVICE_ID
aglit devices attach DEVICE_ID
aglit devices detach DEVICE_ID
```

`devices list` shows enrolled computers. Add `--employee` to list devices
assigned to one employee, including peripherals. Add `--json` for structured
output. `devices discover` finds local phones and virtual devices. Register from a
device descriptor or attach an existing device by its ID.

### Teams

```sh
aglit teams list
aglit teams init --name "Operations"
aglit teams invite EMAIL --team TEAM_ID
aglit teams enroll --team TEAM_ID
aglit teams enroll --team TEAM_ID --codes-file team-codes.json
```

For enrollment, request a security code, then save the selected computer ID
and its code in a private JSON file.

### Repos

```sh
aglit repos list --json
aglit repos init ./website --name "Website"
aglit repos register ./website --team TEAM_ID
aglit repos rename ./website --name "Company website"
aglit repos remove ./website
```

**Aglit Drive** is backed by `~/aglit-ai/`. Copy a folder directly into
the drive to register it for sync, or use `aglit repos register DIRECTORY`
to sync an existing folder in place. `aglit repos init` can create a new
directory. Both commands use the current directory if you omit the path.
Sign in on the participating devices. Use `--team TEAM_ID` for a specific
team, and use the project chip’s **Sync** menu to pause or resume. Sync is
two-way, including file deletions. Removing a registration preserves local
files.

**Sync rules** go at the project root. Files are included by default,
including dotfiles and Git-ignored files. Put common exclusions in
`.aglitignore` using Git ignore syntax. Add exclusions for local secrets
before enabling sync. For example:

```gitignore
/.env
/.env.*
!/.env.example
/node_modules/
```

Use `.aglit-config` (JSON) for per-OS rules. Supported keys under
`sync.platforms` are `darwin`, `win32`, and `linux`. Rules use
project-relative paths with forward slashes and are applied after
`.aglitignore`. Aglit always synchronizes root `.git/`, `.aglitignore`,
and `.aglit-config` across participants.

```json
{
  "sync": {
    "platforms": {
      "darwin": { "exclude": ["/build/windows/"] },
      "win32": { "exclude": ["/build/macos/"] }
    }
  }
}
```

### Pipelines

Commit a `.aglit/pipelines.yaml` file at the repository root, or at each
package root in a monorepo. Aglit reads those files from the registered Git
branch and runs the version at the selected commit. The device controller’s
default state and run history live under `~/.aglit-ai/pipelines/device/`.
Keep that directory on the controller. Supply credentials through the
authorized runner’s environment and keep them out of the repository.

**A minimal pipeline** prints the Node version, then waits for approval
before running the final command. Replace the commands with your own build
and release steps.

```yaml
version: 1
name: Website
stages:
  - id: verify
    name: Verify Node
    command: node --version
  - id: approval-check
    name: Approval check
    manualApproval: true
    command: echo "Release approved"
```

**Pipeline YAML v1**

- Top-level fields are `version: 1`, `name`, and `stages`. Optional fields
  are `description` and `watch`. Use literal package-relative paths in
  `watch` to limit which subsequent changes start a run.
- Every stage has an `id` and one execution field. Use a shell `command`,
  or a `task` with `employeeId` and `message`. Tasks can also specify
  `model` with `provider`, `model`, and `reasoningEffort`.
- Commands run from the package directory by default. Set `workingDirectory`
  to a path relative to the repository root and `employeeId` to target a
  registered employee for a command. Use `retry: automatic` to opt into
  automatic retries.
- Stages run in order. A `parallel` item maps branch names to stage lists.
  The following stage waits for all branches. A stage’s `workflows`
  start after that stage and all finish before the next stage starts.
- Use `manualApproval: true` for a per-run approval gate and
  `enabledByDefault: false` to start a stage disabled. A disabled terminal
  stage can use `needs` to depend on earlier stages in its branch.
- Display fields include `name`, `text`, `url`, and `metadata`. A
  metadata item has a `label` and `text` or an HTTPS `url`. Task stages
  can use an `acceptance` policy for CLI or native-runtime qualification.

Register the repository after pushing its definition. Run each init
example independently.

```sh
aglit pipelines init --branch main
aglit pipelines init --repo https://github.com/example/project.git --branch main
aglit pipelines list
aglit pipelines devices
aglit pipelines promote PIPELINE_ID --to approval-check --run RUN_ID --source FULL_COMMIT
```

`pipelines init` uses the current Git repository’s `origin` when you omit
`--repo`, and defaults to the `master` branch when you omit `--branch`.
Promote a specific run using its stage ID or `branch/stage` path. If the
outcome is uncertain, retry with the same printed request ID via
`--request-id UUID`. Promotion may require native approval and preserves
the saved progression gates.

### Models

```sh
aglit models setup
aglit models list --json
aglit models accounts
```

Use `models setup` to choose the provider account and model for this
computer’s assistant. To add an account or API key, follow the setup
prompt to Desktop’s AI Models settings. `models list` shows model
connections, including those available through enrolled devices.
`models accounts` shows the connected local accounts.

Aglit discovers a signed-in Codex account from the usual local Codex home.

**Account pools**

```sh
aglit models pool work --name "Work accounts" --connections local:ACCOUNT_A,local:ACCOUNT_B
```

Use the local connection IDs from `aglit models accounts`. Pool members
must use the same provider. To use a pool for an employee, select the pool
as the model connection in that employee’s AI Model settings. Aglit
distributes requests among eligible accounts and keeps related requests
on the same account when possible.

**Custom chat endpoints**

In Desktop, open **Model proxying → Custom models → Add endpoint**. Enter
the base URL of a service running on that computer, such as
`http://127.0.0.1:8000`. Desktop accepts HTTP or HTTPS with
`localhost`, `127.0.0.1`, or `[::1]`. You can include a path prefix and
an optional trailing `/v1`. Keep credentials, query strings, and
fragments out of the URL. The local service handles upstream credentials.

- **Discovery (optional)** · `GET /v1/models` returns JSON with unique,
  nonempty model IDs of up to 128 characters. Return an OpenAI-style
  catalog such as `{"object":"list","data":[{"id":"example"}]}` or an Aglit
  catalog such as `{"models":{"chat":[{"id":"example","displayName":"Example"}]}}`.
  Select a returned ID or type one manually. Discovery has a 15-second
  deadline and a 256 KiB response limit.
- **Inference** · `POST /v1/responses` accepts an OpenAI Responses JSON
  request with the saved `model` ID. Return a Responses object for
  non-streaming requests and typed server-sent events with content type
  `text/event-stream` when `stream: true`. For text streaming, implement
  `response.created`, `response.output_text.delta`, and `response.completed`.
  Agent tool use also needs Responses function-call items and matching
  `function_call_output` inputs. Serve both routes directly. A Chat
  Completions server needs a Responses-compatible adapter.
  [Responses streaming events](https://developers.openai.com/api/reference/resources/responses/streaming-events).
  [Responses function calling](https://developers.openai.com/api/docs/guides/function-calling).

Check the service from the original computer before saving the endpoint.
Replace `example` with your server’s model ID.

```sh
curl -fsS http://127.0.0.1:8000/v1/models
curl -fsSN http://127.0.0.1:8000/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{"model":"example","input":"Say hello.","stream":true,"store":false}'
```

**Optional Codex terminal** · `aglit codex` launches standalone Codex
with shared memories. It requires a signed-in Aglit profile with its
native Codex memory harness installed. Model setup and Aglit chats use
their configured harness automatically.

### Employees

```sh
aglit employees list
aglit employees list --capacity --json
```

Use the employee ID in the result with Console, device, task, and chat
commands.

### Tasks

```sh
aglit tasks create --employee EMPLOYEE_ID --name "Review the release" --file task.md
aglit tasks list --employee EMPLOYEE_ID --status active --limit 20 --json
aglit tasks get TASK_ID --employee EMPLOYEE_ID --json
aglit tasks send TASK_ID --employee EMPLOYEE_ID --message "Please review the saved result."
```

Tasks default to this computer. Create a draft with `--name` and one of
`--message` or `--file`. Pass `--status active` to create an active
task. Creating an employee task uses the enrolled device and the app’s
delegation checks. Use `--search` to filter and pass the returned `--cursor`
with the same filters for the next page.

### Chats

```sh
aglit chats list --employee EMPLOYEE_ID --limit 20
aglit chats send --employee EMPLOYEE_ID --message "Summarize this week’s activity."
aglit chats send --employee EMPLOYEE_ID --chat CHAT_ID --file follow-up.md
```

Omit `--chat` to create a chat and send its first message. Use an exact chat
ID to send a follow-up. Chat sends return a queued acknowledgement. Keep the
printed request ID and use `--request-id UUID` to retry the same message after
an uncertain response. A chat on another computer requires the latest CLI
there and an existing authorized private SSH connection. Omit `--employee`
to use the employee installed on this computer.

### Soul

```sh
aglit soul get > soul.md
aglit soul set --file soul.md
```

An employee’s soul is its saved system prompt. `soul get` writes the exact
text. `soul set` accepts a regular UTF-8 file up to 16,000 characters.

### Messages

```sh
aglit messages send --employee EMPLOYEE_ID --task TASK_ID --message "Please review the saved result."
```

`messages send` and `tasks send` queue a follow-up on an existing task.
Use `--file` in place of `--message` for multiline follow-ups. Agents can
pass their original `--source-session UUID` for audit context.

## Self hosting

### Start a server on this computer

```sh
aglit server init local
aglit server validate local
aglit server start local
```

Use `aglit server init ENV` to create or edit an environment. The CLI keeps its
settings in a private `~/.config/aglit/server/ENV/.env` file. Fill in the OAuth
secrets it prompts for in that file. The CLI prints the callback URLs to use when
registering OAuth applications. For one local environment you can run
`aglit server start` directly. The server requires Unix and Node 24. It uses an
installed `aglit-server` or the exact version in `AGLIT_SERVER_VERSION`.

The wizard first asks **local or cloud**. Local runs the server on this computer;
cloud then asks for AWS, GCP, Azure, or an
existing Cloudflare Worker. It configures one OIDC provider per run, with
experimental `tsidp`, Google, or custom OIDC presets. Existing additional
providers remain unchanged. Google fills its issuer automatically but requires
your own registered Web OAuth client and secret.

For local Tailscale login, the default **managed** option downloads a pinned,
checksum-verified tsidp release, creates a dedicated private identity, and prints
its first-time Tailscale enrollment link. Your tailnet administrator must permit
client registration from the setup computer to that identity. The CLI never
edits tailnet policy. It registers the OIDC client automatically and stores its
credentials and persistent node state in the owner-only environment directory.
`server start` supervises that identity alongside the server, reusing its state
on restart. Choose **existing** to supply your own tsidp issuer and client.
Neither option enables Funnel or creates a public endpoint. tsidp is an
experimental BSD-licensed community project; Tailscale account plan limits apply.
Users must sign in from a user-owned Tailscale device: tagged server/controller
nodes have no user identity and tsidp rejects their account login. tsidp 0.0.20
also omits `email_verified`. Aglit requires that signed claim; keep this check
enabled. A tailnet administrator must explicitly map `extraClaims.email_verified`
to `true` only for identities whose email the trusted upstream provider verifies,
scoped to the dedicated tsidp node. Do not assert it for arbitrary tailnet members
or email-like GitHub/passkey identities. First-time setup therefore includes a
small admin policy step; it is not an unattended zero-touch login service.

For `local`, setup selects Tailscale first and fills its HTTPS hostname when the
local client is connected. Existing HTTPS/VPN proxies and development-only
loopback are also available. Login selects the experimental `tsidp` preset first
for a new provider; Google and custom OIDC remain available. Existing ingress choices are retained when editing the same target.
Cloud targets suggest existing HTTPS. AWS, GCP and Azure mean existing EKS, GKE
and AKS clusters; `kubernetes` means another existing cluster. No cluster is
provisioned. Every target runs a server; `local` means running it on the computer
where the command is executed. `managed-release` is an internal release target,
reserved for existing managed release profiles and is not
offered by the setup wizard. Tailscale ingress and OIDC login are separate:
setup never changes existing Serve routes or tailnet access policy.

```dotenv
AGLIT_TARGET=local
AGLIT_INGRESS=tailscale
AGLIT_APP_ORIGIN=https://<your-tailscale-https-hostname>
AGLIT_PORT=59090
AUTH_PROVIDERS='[{"id":"work","type":"oidc","displayName":"Work","issuer":"https://login.example.com","clientId":"aglit","clientSecret":""}]'
```

The origin is the exact URL clients use, including the scheme. The server
listens on loopback. For Tailscale, use the HTTPS hostname shown by Tailscale
Serve and forward it to the loopback listener.

With a custom HTTPS domain, set `AGLIT_INGRESS=existing-https` and point your
existing reverse proxy or load balancer at the listener. The proxy must support
WebSocket upgrades and streaming responses. Use `loopback` for HTTP development
on the same computer.

### Deploy a named environment

```sh
aglit server init company
aglit server validate company
aglit server deploy company
```

`deploy` previews the destination and asks before applying. For unattended
use, `--apply` authorizes application after the preview. The destination
comes from the environment file:

- For `aws` (EKS), `gcp` (GKE), `azure` (AKS), or `kubernetes`, put
  `context`, `namespace`, `storageClassName`, `image`, `proxyImage`,
  `configMap`, and `authSecret` in the `AGLIT_DEPLOYMENT` JSON object. Use
  digest-pinned images, an existing private ingress, and a retained disk class.
  When you use a `.env` profile, the CLI writes its server settings and
  OAuth secrets into the selected ConfigMap and Secret. For legacy JSON
  profiles, provide those resources yourself with `server.json` on port
  59090 and `auth.env`. The runtime uses one replica and retains its disk
  when it restarts.
- For `cloudflare`, put `accountId`, `worker`, and the existing `versionId`
  in `AGLIT_DEPLOYMENT`. The command promotes that version of an existing Worker
  using the scoped token from `CLOUDFLARE_API_TOKEN` or the variable named by
  `tokenEnv`.

### Check or connect to your server

```sh
aglit server check local --probe-auth
aglit server validate --config /path/to/server.json
aglit init --server https://aglit.example.com --auth-provider work
```

`check --probe-auth` checks the local configuration and probes OIDC discovery.
`--config` also accepts an existing server JSON file and its adjacent
`auth.env`. Local validation, checks, and starts accept `--state-dir`,
`--secrets-file`, `--license`, and `--runtime-bin`. Choose this server’s
HTTPS origin and sign-in provider in guided setup. To reset a saved company
server, choose the CLI environment default during `aglit init`.

[Aglit AI Terms of Service](https://aglit.ai/terms/)
