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
- 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 openhttp://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. - 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.
- 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 launchNETWORK_PUBLIC_ORIGINto the same origin andINTERNAL_WEBSITE_PUBLIC_PORTto an explicitly empty string so old launch overrides cannot restore localhost links. Use your server deployment configuration for HTTPS;install.shadvertises its host ports and does not configure a TLS proxy. - 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 route | Private 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.
- Get the release's
docker-compose.ymlanddeploy/searxng/settings.ymltogether, then run the preparation commands below in that checkout. A private repository requires the optional GitHub login first. - Review published ports in
docker-compose.ymlbefore starting. For local use or a host-based HTTPS proxy, change UA mappings to127.0.0.1:18090:18090and127.0.0.1:18600:18600. Remove the SearXNG and Crawl4AIportsentries if you only use them from UA; their services remain reachable on the Compose network. - 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 rundocker compose up -danddocker 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 ascurrentContext. For a new file, use{"credsStore":"osxkeychain"}. - Windows: Docker Desktop configures its
desktophelper. Complete sign-in from your regular desktop session. - Linux: configure
secretservicewith an unlocked desktop keyring, or initializepassand 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.
| Provider | Signup and credential steps | Choose in UA |
|---|---|---|
| OpenRouter | Sign 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 API | Create 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. |
| Anthropic | Sign 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 Gemini | Sign 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 host | Create 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
- Create or sign in to your xAI account and confirm it has the model/API entitlement you need.
- In Runtime Basics, choose xAI Grok OAuth, then Connect xAI.
- Open the displayed verification page, approve the device code, and wait for UA to report that credentials were saved.
- 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
- Exa: sign up at the Exa dashboard, create an API key, and enter it in UA's Exa Search API Key field. Follow the Exa setup instructions.
- Brave Search: create a Brave Search API account, choose an API plan, generate a subscription key, and enter it in Brave Search API Key. A Brave browser account alone is not an API subscription. See API authentication.
- SearXNG: run your own service using the optional Compose stack. Generate a random
SEARXNG_SECRETon the host and configure its URL so UA can reach it. - Crawl4AI: the Compose stack supplies its HTTP and MCP URLs and a host-generated API token mounted as a Docker secret. The token authenticates extraction requests; it is not a model or Web Chat key.
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.
| Setting | First-run choice |
|---|---|
| Your name and assistant name | Choose how you and your assistant should appear in conversations. |
| Model provider, endpoint and model | Select 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 repositories | Keep 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 search | Keep local storage defaults. Search credentials are optional for the first conversation. |
| Chat channels | Keep Web Chat. Add Telegram, Discord, or other channels later using the channel guides. |
| Access token | Save 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
- Open @BotFather in Telegram, send
/newbot, choose a name and username, and save the bot token. - 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.idfor the sender andmessage.chat.idfor the chat. Avoid putting the token in browser history or shared logs. - 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. - 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
- Open the Discord Developer Portal, create an application, and configure its bot. Save the bot token.
- 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.
- 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.
- 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
- Deploy an authenticated signal-cli-rest-api service separately. Follow that service's instructions to link it as a device or register a number.
- Record the bridge URL reachable from UA and the linked/registered Signal account in E.164 format, such as
+15551234567. - 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
- Create an account at Photon and create or select a Spectrum project in its dashboard.
- 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.
- 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.
- 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.