Skip to content

Private and offline deployment ​

A private deployment runs all of Yi Code inside your network: the control plane, the knowledge service and the execution hosts. It can run fully offline. Sign-in, Git, models, images and tools all come from inside your network.

The offline package installs on a clean host with no internet access, without pulling images and without outbound traffic. Contact us to plan a private deployment.

What we deliver ​

An offline bundle with a checksum file (SHA256SUMS) covering everything in it:

  • The control plane as Docker Compose services: database migration, API, worker and PostgreSQL.
  • The knowledge service: RAGFlow v0.27.2 (Apache 2.0) with Elasticsearch, MySQL, MinIO and Redis, set up for CPU only, with RAGFlow's code execution and extra GPU services off.
  • The execution host packages: Docker, containerd, Docker Compose and Buildx, gVisor, OpenSandbox and the Yi Code runner and broker.
  • Every container image, pinned by digest and checked by image ID after loading.
  • The scripts that configure and install all of the above.

No model weights or inference platform are included.

What you provide ​

Requirement
IdentityAn OpenID Connect provider. By default Yi Code calls its userinfo endpoint to recheck members and roles
GitYour Git server, reachable from the control plane
ModelsAn OpenAI-compatible /v1 chat endpoint with tool calling and usage reporting, and an embedding service for the knowledge base. See Models
Control plane hostA Linux host with Docker, and your internal CA certificates
Execution hostsFresh, dedicated Ubuntu 24.04 amd64 machines, one turn at a time per host. ARM, macOS and running without gVisor are refused
Control plane addressAn HTTPS reverse proxy in front of the API, which listens only on 127.0.0.1:8000. Its address is YI_PUBLIC_URL, which production requires to be HTTPS. Execution hosts must reach it, including YI_GATEWAY_URL. An internal certificate is fine
Execution host networkA trusted reverse proxy with an internal certificate in front of each execution host's broker, reachable from the control plane

For more than one API replica, use your own highly available PostgreSQL and S3-compatible object storage instead of the bundled database and local volume.

What is switched off ​

  • Online payment. Usage is billed by contract, see Budget and billing.
  • Any fallback to public model endpoints.
  • SDK telemetry.

Your network policy should block outbound internet traffic as well.

Install ​

BUNDLE stands for the bundle's path. The bundle's scripts are in BUNDLE/deploy/ and run with python3.

  1. Check where the delivery came from. The installers verify every file against the checksum file before they change anything.

  2. On the control plane host, generate the installation's own random passwords and secrets. The script refuses to overwrite existing ones.

    sh
    python3 BUNDLE/deploy/configure.py BUNDLE/deploy
  3. Edit BUNDLE/deploy/private.env: your internal URLs, the identity provider and the claim that carries the role, the allowed hosts. Import your internal CA. See Configuration. If one identity provider serves many teams, map roles from a signed role claim. Don't map every internal user to administrator.

  4. Install the control plane and the knowledge service. This verifies every file, loads the images, checks their IDs and starts the services without pulling anything.

    sh
    python3 BUNDLE/deploy/install.py BUNDLE

    The API then listens on 127.0.0.1:8000. Put your HTTPS reverse proxy in front of it at the address in YI_PUBLIC_URL.

  5. On each fresh execution host, with a copy of the bundle, render the host's own credentials, then install as root. --control-url is the control plane's HTTPS address.

    sh
    python3 BUNDLE/deploy/render_host.py BUNDLE /FRESH-CONFIG --control-url https://agent.corp.internal
    sudo python3 BUNDLE/deploy/install_host.py BUNDLE --configuration /FRESH-CONFIG

    The installer verifies the files, installs the bundled packages from local files, loads and checks the images, sets up the closed sandbox network and runs a gVisor probe. The host's broker is switched on only if the probe passes. The evidence is written to /var/lib/yi-agent/offline-native-probe.json. The installer refuses a host that already has configuration or containers. After a restart, the network isolation rules are restored first.

  6. Connect each host to the control plane:

    • The broker listens on the host's loopback address. Put a reverse proxy with an internal certificate in front of it, and add its host name to YI_CONNECTOR_HOSTS.

    • Copy the value of YI_BROKER_KEY from the host's /FRESH-CONFIG/broker.env into BUNDLE/deploy/private.env under a name that starts with YI_BROKER_KEY_, for example YI_BROKER_KEY_HOST_1.

    • Apply the changed private.env by recreating the API and the worker, from BUNDLE/deploy with the image variables described in Run yi-admin:

      sh
      docker compose up -d --force-recreate api worker
    • Register the host as a static execution pool, see Register an execution host.

  7. Point RAGFlow at your embedding service, create the account for your organization and register its dataset as a knowledge source in Yi Code.

  8. Run an acceptance task with the network cut off, and confirm that nothing tried to reach the internet.

Run yi-admin ​

yi-admin exists only inside the control image, so it runs in the API container. Run Docker Compose from BUNDLE/deploy, with the same two image variables the installer used. Their values are in BUNDLE/transport.json:

sh
cd BUNDLE/deploy
export YI_CONTROL_IMAGE="$(python3 -c 'import json; print(json.load(open("../transport.json"))["control"])')"
export YI_POSTGRES_IMAGE="$(python3 -c 'import json; print(json.load(open("../transport.json"))["postgres"])')"
docker compose exec api yi-admin --help

Without those two variables, Docker Compose refuses to read the project.

A file you pass to yi-admin must be visible inside the container. Pipe it in on standard input, as below, rather than giving a path on the host.

Register an execution host ​

Write a pool.json for the host:

json
{
  "name": "host-1",
  "cloud": "static",
  "region": "on-prem",
  "capacity": 1,
  "healthy": true,
  "budget_micro": 0,
  "cost_micro_per_second": 0,
  "price_micro_per_second": 0,
  "config": {
    "broker_url": "https://broker-1.corp.internal",
    "broker_key_ref": "YI_BROKER_KEY_HOST_1",
    "runtime_image": "the value of YI_RUNTIME_IMAGE in private.env"
  }
}
  • broker_url is the reverse proxy in front of the host's broker. broker_key_ref names the variable you added to private.env.
  • runtime_image must equal YI_RUNTIME_IMAGE in private.env. A pool with a different image never gets turns.
  • Set healthy to true only for a host whose probe passed.
  • Amounts are in millionths of a dollar. price_micro_per_second is what turns are charged for execution time. A budget_micro of 0 works when cost_micro_per_second is 0.

Then, from BUNDLE/deploy with the variables above:

sh
docker compose exec -T api yi-admin pool-import /dev/stdin < pool.json

Git and pull requests ​

Repositories are added in "Settings" by URL, with a credential reference for read access. Their host must be in YI_GIT_HOSTS. Set the project's "Allowed clouds (comma-separated)" to static, the type of your execution pools. Draft pull requests are created only for repositories on github.com. With an internal Git server, take each session's changes from changes.patch.

Runtime image ​

The bundle includes the default runtime image, with Python and Node.js. You can build your own with other toolchains. It must pass the isolation and execution checks again before it is used. See Runtime image.