Universal Agents

Set up Universal Agents.

Install on your computer, run your own server, or connect to an existing service. Prepare provider accounts and choose your settings before onboarding.

This guide runs locally. It displays commands for you to review and run; it does not execute them or collect credentials. You do not need a source checkout or a compiler.

1. Connect to your hosted service

You only need a browser on Windows, macOS, or Linux. Docker, WSL, and Colima belong on the machine running the service; they are not required on your client computer. The desktop app manages a local Docker runtime and does not connect to arbitrary remote servers.

Enter the browser-facing origin, including a custom port if needed, for example https://assistant.example.com:8443. Leave off /webchat, paths, queries, credentials, and fragments. This is the UA service address, separate from your model provider's API endpoint.

Open initial setup · Open Web Chat · Open service documentation

If an administrator has already set up the service, open Web Chat and use the sign-in or invitation details they supplied. Provider setup and server configuration below are for the service owner. A model API key is not your Web Chat login.

Hosting your own server: initial access, HTTPS, and advertised URLs
  1. On the server, follow Container only using its operating system and persistent data directory. Start with loopback port bindings. If the server is remote, forward its default ports from your client terminal with ssh -N -L 18090:127.0.0.1:18090 -L 18600:127.0.0.1:18600 user@your-server, then open http://127.0.0.1:18090/. Change both sides of each forwarding rule if you selected other ports. Keep this initial setup private until your account is created.
  2. Point your hostname at the server and configure a trusted HTTPS certificate. Use one public origin for the website and browser-facing broker forms. The route table below assumes the proxy reaches the server's loopback ports; a containerized proxy must use a shared private network and the UA service name instead.
  3. After onboarding, merge the generated settings below into the server instance's instance_config.yaml, preserving its other settings. These instructions apply to a server-managed instance; the desktop launcher owns its local runtime configuration. Set container launch NETWORK_PUBLIC_ORIGIN to the same origin and INTERNAL_WEBSITE_PUBLIC_PORT to an explicitly empty string so old launch overrides cannot restore localhost links. Use your server deployment configuration for HTTPS; install.sh advertises its host ports and does not configure a TLS proxy.
  4. Restart the UA service and verify Web Chat sign-in, /docs, and /auth status. Generated browser authentication, credential-collection, and account-link links should start with the external URL. Restart policies must restart after a successful onboarding exit; keep one instance replica with durable /data.
Public routePrivate destination
/auth/…, /credential-collection/…, /account-link/…Broker, default port 18600; give these routes higher priority
All remaining routes, including /, /webchat, assets, /api/…, and /docs/Website, default port 18090; preserve streaming and WebSocket connections

Keep the broker's /v1/… API private. Forwarding only /webchat breaks its assets and login calls. A URL prefix such as /ua, or a separate broker hostname, is not supported by generated links.

Both public ports are null behind HTTPS, so links use the external origin as entered, including an explicit port such as 8443. Bind ports remain the internal service ports. Use the complete Traefik/Swarm example for deployment configuration, storage, routing, and first-run restart behavior. Changing a URL in this guide does not deploy a proxy or change your server.

1. Prepare your computer

Install Homebrew and follow its printed PATH instructions. Then use Colima to run Linux containers on Apple Silicon or Intel.

These are starting allocations, not space reserved for your model. Cloud models run remotely. The profile is named universal-agents; Docker will use its context. Keep agent workspaces under your home directory, or configure an explicit writable mount in Colima for another location.

After restarting your Mac, run colima start universal-agents before opening the app or starting the container. Desktop start-at-login does not start Colima.

Use Windows 11 x64 with hardware virtualization enabled. In administrator PowerShell:

wsl --install -d Ubuntu
wsl --update
wsl --list --verbose

Restart if prompted. Open Ubuntu once and create its Linux username and password. Its version should be 2. An existing WSL 1 distro can be converted with wsl --set-version Ubuntu 2.

Install Docker Desktop for Windows, start it, select Use the WSL 2 based engine, and use Linux containers. For container-only installation, enable Ubuntu under Settings → Resources → WSL Integration. See Microsoft's WSL instructions.

Install the native Windows launcher in Windows, not inside Ubuntu. The installer supplies WebView2 if needed. Use a local Windows folder for your agent workspace; WSL network paths and UNC shares are not supported.

Run the installation commands below in the Ubuntu terminal. Its home directory and Docker login are separate from Windows.

For the desktop app, use an Ubuntu 24.04 x64 graphical desktop. The container also runs on Linux arm64 and does not need a graphical session.

Install Docker Engine using the instructions for your distribution. For Ubuntu, follow the official apt repository setup, then install the listed Docker packages.

sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

Sign out and back in before continuing. Docker group membership grants root-level Docker access; rootless Docker is another option. The launcher must reach Docker as your normal user, without sudo.

Verify Docker is ready in the same user account that will run Universal Agents:

docker info

2. Choose your launch settings

Defaults keep the website and secure broker on this computer. Model keys are entered later in the real onboarding page.

Network settings for local or private LAN installation

--public-origin supplies NETWORK_PUBLIC_ORIGIN, used in browser and credential-redirect links. For direct LAN access, enter the server's HTTP origin without a port, such as http://192.168.1.50, and bind to that host interface. The web and broker ports above are added separately. 0.0.0.0 listens on every IPv4 interface; it is never a browser URL. Restrict access to trusted clients and keep first onboarding private. For public HTTPS, use Hosted server and its reverse-proxy configuration.

On Windows, the data path is a Linux path inside Ubuntu. On macOS, use a directory shared with Colima. Keep /data backed up; stopping or recreating an installer-managed container preserves it.

Run these in Terminal on macOS/Linux, or Ubuntu on Windows. The installer and release image come from the same release. For LAN or public hosting, use the HTTPS reverse-proxy guide.

Optional Compose stack with SearXNG and Crawl4AI

Use Compose instead of the standalone installer when you want the bundled search and extraction sidecars. Do not start both stacks on the same ports or data directory. Install the Docker Compose plugin for your server and confirm docker compose version succeeds; Docker Desktop includes it. For Colima, follow Compose installation for the Docker CLI on macOS.

The instance name selects HOST_ROOT/INSTANCE_NAME for persistent /data; choose your assistant's display name separately in onboarding. BUILD_VER uses the numbered runtime image above. Keep INSTANCE_ROOT=/data. This Compose recipe uses the repository's fixed ports 18090 and 18600; standalone custom-port fields do not change its YAML.

  1. Get the release's docker-compose.yml and deploy/searxng/settings.yml together, then run the preparation commands below in that checkout. A private repository requires the optional GitHub login first.
  2. Review published ports in docker-compose.yml before starting. For local use or a host-based HTTPS proxy, change UA mappings to 127.0.0.1:18090:18090 and 127.0.0.1:18600:18600. Remove the SearXNG and Crawl4AI ports entries if you only use them from UA; their services remain reachable on the Compose network.
  3. Keep the generated secret file and SearXNG secret with your private deployment configuration. Reuse them for subsequent starts. In the same terminal, review docker compose config, then run docker compose up -d and docker compose logs --tail 100 ua. The rendered configuration contains the SearXNG secret; do not share it.

UA reaches http://searxng:8080 and http://crawl4ai:11235 inside this network, with Crawl4AI MCP at http://crawl4ai:11235/mcp/sse. The Compose file supplies these URLs and gives the Crawl4AI container its token as a secret. Universal Agents keeps that token in its credential store: after the first start, an administrator links it in chat with /link http:crawl4ai team and /link mcp:crawl4ai team. Leave CRAWL4AI_EXECUTE_JS_ENABLED=false unless you deliberately need page JavaScript execution in the Crawl4AI container. See Docker operations for service details.

2. Install the desktop app

Download one installer and its matching .sha256 file from Desktop 0.6.3. The launcher selects its reviewed runtime image automatically.

macOS uses a universal DMG with an ad-hoc signature and no notarization. Apple Silicon execution was tested; Intel was compiled. Windows installers are unsigned. Only approve operating-system prompts for an artifact whose origin and checksum you have checked.

Open the DMG and drag Universal Agents to Applications. If macOS blocks it, use System Settings → Privacy & Security → Open Anyway. Keep Gatekeeper enabled.

The DEB installs its desktop library dependencies. For AppImage, Ubuntu 24.04 needs sudo apt install libfuse2t64, then chmod +x the downloaded file. Other Linux userspace baselines have not been verified. GNOME may need an AppIndicator extension for the tray; relaunching the app also restores its window.

Optional: GitHub access for restricted repositories or packages

Public downloads need no special access. Use this section only for restricted downloads, or for the current launcher's GitHub CLI-based update checker. Public updates can also be downloaded from the releases page without signing in.

Install GitHub CLI: brew install gh on macOS, winget install --id GitHub.cli --exact in Windows PowerShell, or sudo apt install gh on Ubuntu. For container-only installation on Windows, install and sign in to gh inside Ubuntu.

gh auth login --hostname github.com --web --scopes read:packages
gh auth status

Use an account with access to both repositories and the runtime package, and approve organization SSO if required. An existing login can add the package scope with gh auth refresh --hostname github.com --scopes read:packages.

Configure Docker's credential helper before signing in
  • macOS with Colima: run brew install docker-credential-helper. In ~/.docker/config.json, add "credsStore": "osxkeychain" while preserving existing keys such as currentContext. For a new file, use {"credsStore":"osxkeychain"}.
  • Windows: Docker Desktop configures its desktop helper. Complete sign-in from your regular desktop session.
  • Linux: configure secretservice with an unlocked desktop keyring, or initialize pass and its Docker helper. Follow Docker's credential-store instructions. The launcher refuses plaintext token storage.

Download the private preview with the command below. Open the launcher, choose Click to Begin, then Got it on the one-time notice that agents need a computer that stays on. Expand Private Image Access and choose Sign in with gh; successful terminal login continues installation automatically. If already signed in, choose Use GitHub CLI. If Docker is already signed in, choose Verify access and retry.

The login pipeline sends the token directly to Docker; do not print or paste tokens into this guide. Never put credentials in your agent workspace.

Prepare your model provider account

Choose one provider to start. Create its account, enable the API access or subscription entitlement you intend to use, and check its current billing and model availability. Enter secrets only in the real Universal Agents onboarding page. This offline guide does not test connections or save your entries.

ProviderSignup and credential stepsChoose in UA
OpenRouterSign in at OpenRouter, add credits if required by your chosen model, and create an API key. Copy an exact model ID from the model catalog. See its API quickstart.OpenRouter; API base https://openrouter.ai/api/v1. A fresh install defaults to deepseek/deepseek-v4.1-flash; confirm that model is available to your account.
OpenAI APICreate an account or sign in to the OpenAI platform, select your project, configure API billing, and create a key in API keys. Follow the API quickstart.OpenAI; use the API key and an available API model ID. ChatGPT subscription login uses the separate Codex OAuth path below.
AnthropicSign in to the Claude Console, configure API billing, and create an API key for your workspace. Follow Get started with Claude.Anthropic; enter your API key and the exact Claude API model ID you selected.
Google GeminiSign in to Google AI Studio, select or create a project, and create an API key. Check the project's model access and billing requirements in the Gemini key instructions.Google AI; enter the Gemini API key and an available Gemini model ID.
Another API hostCreate an account with your provider and obtain its API key, exact model ID, and documented OpenAI-compatible base URL. An endpoint can be hosted by a third party or your own model server.OpenAI Compatible. Include the API prefix the host expects, often /v1. This endpoint is distinct from the external UA service URL.
OpenAI Codex OAuth: use subscription authentication

Sign in with a ChatGPT account that has Codex access. Install Codex CLI using the official installation instructions, then create a dedicated file-backed login outside your agent workspace. See official authentication instructions for device-login availability and account restrictions.

mkdir -p "$HOME/.ua-codex-bootstrap"
CODEX_HOME="$HOME/.ua-codex-bootstrap" codex login --device-auth -c 'cli_auth_credentials_store="file"'
mkdir -p "$HOME/.ua-codex-bootstrap"
CODEX_HOME="$HOME/.ua-codex-bootstrap" codex login --device-auth -c 'cli_auth_credentials_store="file"'
# Run in Windows PowerShell for the native desktop app.
$UaCodexHome = Join-Path $env:USERPROFILE '.ua-codex-bootstrap'
New-Item -ItemType Directory -Force -Path $UaCodexHome | Out-Null
$UaPreviousCodexHome = $env:CODEX_HOME
try {
  $env:CODEX_HOME = $UaCodexHome
  codex login --device-auth -c 'cli_auth_credentials_store="file"'
} finally {
  $env:CODEX_HOME = $UaPreviousCodexHome
}

For a container managed inside WSL, create the dedicated login in Ubuntu with mkdir -p "$HOME/.ua-codex-bootstrap" and CODEX_HOME="$HOME/.ua-codex-bootstrap" codex login --device-auth -c 'cli_auth_credentials_store="file"', then follow the container import instructions.

In the launcher's OpenAI subscription section, choose the generated auth.json, start UA, and finish the import before testing the model connection. Select OpenAI Codex OAuth in onboarding. The import copies credentials into the instance-owned auth store and supports later refresh.

For a container or hosted service, the service owner must import the login into that instance's auth store, or mount the dedicated Codex home read-only using the UA container/import instructions. A login on your client laptop alone does not authenticate a remote runtime. A read-only shared login must be refreshed on its originating host.

Treat auth.json as a secret. Do not upload it to the guide or place it in a project that agents can read. Model login is separate from GitHub access and the tool-broker /auth command.

xAI Grok OAuth: connect your account during onboarding
  1. Create or sign in to your xAI account and confirm it has the model/API entitlement you need.
  2. In Runtime Basics, choose xAI Grok OAuth, then Connect xAI.
  3. Open the displayed verification page, approve the device code, and wait for UA to report that credentials were saved.
  4. Choose an available model, then use Test Connection. A successful login does not by itself guarantee model access.

The runtime owns and refreshes the OAuth store. XAI_API_KEY is a different authentication method and is not a fallback for this provider. See xAI login and troubleshooting.

Local models: Ollama or vLLM

Install Ollama or deploy vLLM's OpenAI-compatible server, download a model that supports the tool calling you need, and confirm the model server runs before UA. Local models need their own RAM, disk, and possibly GPU capacity in addition to the UA container.

Select OpenAI Compatible in UA. Use the model server's exact model name and base URL; Ollama normally exposes http://MODEL_HOST:11434/v1. Its local compatibility API uses a non-secret placeholder such as ollama if the client requires a key. Use a real token when your server enforces authentication. See Ollama's API instructions.

The endpoint must be reachable from the UA container or server. Container localhost means that container, not your laptop. Docker Desktop can use host.docker.internal; Colima and Linux need a reachable host/VM address or a shared container-network service name. Verify the route and model-server bind address in your deployment. For hosted UA, an Ollama server on your laptop is not automatically reachable.

Model settings to carry into onboarding

These notes are a worksheet, not an imported configuration. Choose reasoning effort and context-window size only when you know the selected model's limits; mark image, audio, and file support independently. Leave model failover disabled for the first setup. Changing provider clears the model choice so you can select one valid for that account.

Optional search accounts and web extraction

Search is optional for your first conversation. Check current provider plans and quotas; this guide does not promise a free tier. Use onboarding's credential fields or the runtime's secure credential flow, not this HTML file.

3. Complete onboarding

After access is confirmed, the launcher downloads and starts Universal Agents; the first download can take several minutes. If it is stopped, choose Start. Optionally use Choose folder under Agent workspace, then choose Open in app when the status says Setup ready.

After installation, open the local setup page. If it is not ready yet, inspect the startup logs with the command below.

For a new instance you own, use Open initial setup above. If your administrator already configured the service, use Open Web Chat and skip instance onboarding.

SettingFirst-run choice
Your name and assistant nameChoose how you and your assistant should appear in conversations.
Model provider, endpoint and modelSelect your provider and a model your account can use. Enter its credential in onboarding, then use Test Connection. See provider setup for subscription and local-model options.
External skill repositoriesKeep the reviewed ua-skills repository or enter other public GitHub skill repositories you trust. Desktop users can later enable Refresh external skills on start to pull these repositories before agents launch.
Storage and searchKeep local storage defaults. Search credentials are optional for the first conversation.
Chat channelsKeep Web Chat. Add Telegram, Discord, or other channels later using the channel guides.
Access tokenSave the Web Chat access token shown during setup. It is separate from your model-provider credential.

Choose Launch team, sign in to Web Chat, and send a message. Type /tour for a walkthrough.

Optional chat channels

Start with Web Chat, then enable only the channels you need. Enter bot credentials in the real onboarding form or the runtime's secure credential flow. Record exact user, group, and channel IDs; an assistant's display name is not an access-control identity.

Telegram: create a bot and find chat IDs
  1. Open @BotFather in Telegram, send /newbot, choose a name and username, and save the bot token.
  2. Start a direct conversation with your bot and send a message. Before UA starts polling, inspect the bot's getUpdates response using a private API client. Record message.from.id for the sender and message.chat.id for the chat. Avoid putting the token in browser history or shared logs.
  3. For groups, add the bot and capture that group's exact chat ID. In BotFather, use /mybots → Bot Settings → Group Privacy when the bot needs ordinary group-message visibility; Telegram may require re-adding the bot after changing privacy. See privacy mode.
  4. In UA, enable Telegram, enter its bot token and allowed chat/user IDs, then configure group policy and mention markers. Record any topic/thread ID if replies should use a specific forum topic.

Stop your manual updates client before launching UA to avoid competing polling consumers. See Telegram configuration.

Discord: create a bot and collect server/channel IDs
  1. Open the Discord Developer Portal, create an application, and configure its bot. Save the bot token.
  2. Enable Message Content Intent when the bot needs channel message content, then generate an installation link with bot/application-command scopes and the permissions it needs to view channels, read history, send messages, and use threads. Follow Discord's bot setup.
  3. Install it in your server. Enable Developer Mode in Discord's Advanced settings, then copy the server, channel, and user IDs from their context menus.
  4. Enable Discord in UA, enter the token, and set allowed users/channels, group policy, and mention behavior. Test in a channel the bot can access.

See Discord configuration for threads and delivery.

Signal: link an account to a REST bridge
  1. Deploy an authenticated signal-cli-rest-api service separately. Follow that service's instructions to link it as a device or register a number.
  2. Record the bridge URL reachable from UA and the linked/registered Signal account in E.164 format, such as +15551234567.
  3. Enable Signal in onboarding. Supply its REST API URL, account, allowed sender IDs, allowed group IDs, and mention policy. Use the actual sender UUID or phone and group ID emitted by your bridge.

A local bridge on your laptop is not reachable from a hosted UA instance without network configuration. See Signal setup and verification.

Photon / iMessage: create a Spectrum project
  1. Create an account at Photon and create or select a Spectrum project in its dashboard.
  2. Obtain the Project ID and Project Secret. Enter them in UA's iMessage/Photon onboarding fields and enable that channel. The runtime bundle already includes its Node.js sidecar.
  3. Send a message through your assigned Photon line and record the exact sender/chat IDs from UA gateway metadata. Use those IDs for allowed senders/groups and proactive delivery.
  4. For group chat, include the assigned Photon line, confirm a group event reaches the gateway, then configure that group ID and a mention marker such as @Ava. Shared-pool delivery and group creation depend on your Photon plan.

See Photon configuration for exact identity handling and group troubleshooting.

Link additional channel identities to your existing UA user through the administrator's /user flow. Set a default delivery channel, chat ID, and optional thread ID if agents should send proactive updates there. Verify one direct reply, one allowed group reply, and proactive delivery before relying on a channel. See allowlists, mentions, and delivery.

Stop, restart, and keep your data

Use the launcher's Stop and Start controls. Enable Refresh external skills on start only when onboarding has at least one approved external skill repository and you want it pulled before each launch. Closing a window leaves the app in the background. Quitting the desktop app leaves the runtime running. Use the launcher's reviewed update flow; do not replace its container manually. If an operation fails, choose Download diagnostics to save exact details.

Closing your browser does not stop the remote service. Its administrator manages restarts, upgrades, credentials, and backups on the server. Your client computer does not contain the server's persistent data.

Stopping preserves your data. To move to a new version, back up the data directory and follow Moving a team to a new version. Do not use volume deletion or global Docker pruning as a routine cleanup step. Existing instances older than UA 0.4.4 need the active-task upgrade instructions.