Skip to content

install.md

Latest commit

 

History

History
105 lines (70 loc) · 6.17 KB

install.md

File metadata and controls

105 lines (70 loc) · 6.17 KB
Raw
title Install Core and Web

This guide takes an operator from an empty host to a working installation: Core, the Web console and PostgreSQL running under Docker, a sandbox backend, a default model and a first Project API key. Web's Overview tracks the same steps in its Getting started checklist.

  1. Check the prerequisites.
  2. Run the installer.
  3. Sign in to Web.
  4. Add sandbox capacity.
  5. Set a default model.
  6. Issue a Project API key.

Every installer flag, existing reverse proxies and offline hosts are in Installation options.

Prerequisites

Linux macOS Windows
Host amd64 or arm64, with curl Intel or Apple Silicon, with curl x64, with PowerShell
Docker Docker Engine, running Docker Desktop, running Docker Desktop, running Linux containers
Account A member of the docker group, or rootless Docker Your user Your user
  • Docker Engine 26 or newer and Docker Compose 2.26.0 or newer, on every platform. Docker Desktop must be recent enough to include them.
  • The Docker daemon can reach the container registries. It does not read this shell's proxy variables; see offline hosts. Release downloads also require access to GitHub.
  • Port 8080 is free, and Docker can publish it; see ports. The installer does not change host policy.

Warning

Run the installer and oac as that account, never with sudo. A sudo run leaves files in ~/.oac owned by root, and later runs fail.

Install

::: code-group

curl -fsSL https://openagentcore.dev/install.sh | bash
irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1 | iex

:::

The installer checks Docker and the port, writes the installation directory ~/.oac/core with its .env and the oac command (oac.exe on Windows), and starts the services. Web serves the console on port 8080 and forwards API requests to Core. Downloads and configuration checks finish before the installation directory is created, so a failed new installation leaves nothing behind. It prints the console address and, on a fresh installation, the Core key; a rerun prints oac core-key --show instead.

The console address defaults to this host's private IP on the default route, or http://localhost:8080 when there is none. Browsers must open exactly that address. To choose it yourself, for example the HTTPS address of an existing reverse proxy, pass --public-url. To pass flags on Windows, see Pass flags.

::: code-group

curl -fsSL https://openagentcore.dev/install.sh | bash -s -- --public-url https://core.example
& ([scriptblock]::Create((irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1))) --public-url https://core.example

:::

Tip

Rerunning is safe. If the installer stops on a failed check, on a service that is not healthy within three minutes, or on Ctrl-C, fix what the message names and run the same command again. A rerun keeps the configuration and data and reuses existing images. --public-url, --host and --web-port apply only to a new installation; to change them later, edit .env and run oac apply. On Linux and macOS the launcher also resumes an unfinished download. Troubleshooting lists the messages.

To move to a newer release, reinstall: uninstall the installation, then run the installer again.

Sign in to Web

  1. Open the console address the installer printed, the public URL. Web accepts only that host.

  2. Sign in with the Core key, the installation's administrator credential. Web has no user accounts.

    ~/.oac/core/oac core-key --show

    On Windows, use & "$HOME/.oac/core/oac.exe" core-key --show. The same command arguments work on every platform.

Add sandbox capacity

The installer selects no sandbox backend. Choose a sandbox backend: microsandbox on your own Linux nodes with workspace storage from Set up workspace storage is the recommended self-managed deployment, and E2B needs no nodes. Applications can also run self-hosted Sessions on their own machines.

Set a default model

Core-hosted Sessions that bring no model provider use their Harness's default model. See default models.

  1. Open Settings → Models and credentials. Under Default model configuration, the Harness marked Default shows Model provider not set. It is Codex unless you changed OAC_DEFAULT_HARNESS; see settings.
  2. Choose Set and enter the model ID, the protocol, and the provider's base URL and API key.
  3. Save. The Harness shows Ready.

Issue a Project API key

  1. On Projects and keys, choose Create project, then Issue key. The dialog shows the key once: copy it and keep it safe. Its How to call card shows the API base URL and sample requests.
  2. Give the key and the API base URL to the application developer. They continue with Run your first Session.

Reach Core from other machines

This step is optional for a trial on one machine. Applications, nodes and sandboxes reach Core at one address, the public URL. HTTP is enough on the local network; beyond it, put a reverse proxy in front and set the public URL to the HTTPS origin it serves. Configure the public address covers the reverse proxy, ports and changing the address later.

Next steps

Next Where
Make an API call Run your first Session
Add Linux nodes Add and manage nodes
Back up and uninstall Operations
Flags, Compose and offline hosts Installation options