Skip to Content

Runtime Modes

isA runs in three modes. The web client always looks and behaves the same — what changes is where your agent’s reasoning and tools actually execute, and whether a cloud account is involved.

ModeExecutionCloud accountBest for
cloudHosted isA cloud (the isA SaaS)RequiredZero setup, managed availability, cross-device access — the default at api.isagent.io 
edgeLocal client + local isA Mate executionRequired (bound to one cloud edition)Local-first with cloud models, A2A teams, memory sync, auth, and billing
localLocal client + local isA Mate executionNoneFully offline, anonymous, no cloud account at all

cloud is what most people use — sign in at the isA cloud and start chatting, no install required. local and edge both run isA Mate on your own machine; they differ in whether that local runtime reaches out to a cloud edition for heavier capabilities.

Migration note: Older configs and deployments may still use the long-form names local_standalone, local_edge, and hosted_saas. These are accepted everywhere as aliases for local, edge, and cloud respectively — new configuration should use the canonical short names.

Choosing a mode

  • Just want to try isA? Use cloud — go to the isA Console or your organization’s isA cloud URL and sign in. No local install needed.
  • Want everything on your machine, no account, fully offline? Use local.
  • Want to run locally but still want cloud models, A2A team delegation, memory sync, or billing? Use edge.

What’s different in local mode

local mode runs entirely on your machine with no cloud account:

  • Cloud-only surfaces (things like the hosted Console, cost-audit, and knowledge/dream/hunt agents) are hidden from the web client.
  • Tasks, notifications, and calendar are powered by the local isA Mate backend’s own scheduler — not a cloud service.
  • External calendar sync (Google/Outlook) is not yet available in local mode; the calendar surface shows Mate’s own scheduled automations only.
  • There’s no login — the client uses a fixed local identity and an unmetered local session.

edge mode restores the cloud-only surfaces and adds cloud models, A2A team delegation, memory sync, auth, and billing, while still running the agent runtime locally.

Installing isA Mate for local or edge

Both local-execution modes are installed the same way, via isA Mate’s installer:

curl -fsSL https://raw.githubusercontent.com/xenoISA/isA_Mate/main/install.sh | bash

Pass --mode to pick which profile becomes your default local configuration:

# Fully local, no cloud account
./install.sh --mode standalone
 
# Local execution, bound to a cloud edition
./install.sh --mode edge

--mode standalone copies config.local-standalone.yaml, and --mode edge copies config.local-edge.yaml, to ~/.isa/isa_mate/config.yaml — the active config isa-mate reads at startup. You can switch modes later without reinstalling by passing --config or setting ISA_MATE_CONFIG.

local (standalone)

Run the onboarding wizard to select a provider:

isa-mate init

The wizard detects what’s available on your machine and lets you choose a provider — Ollama  for free local inference, or a subscription provider (anthropic-sub, codex-sub) if you have one. When Ollama is detected, local mode can use it automatically; otherwise isa-mate init will walk you through configuring a provider before you can chat.

Then start the gateway:

isa-mate serve

Or bring up the full local stack — model service, Mate gateway, and the web client — in one command from an isA_Mate checkout:

isa up
# Model:    http://localhost:8082
# Gateway:  http://localhost:18789
# Web:      http://localhost:4100

edge

Edge needs a cloud account and binds to exactly one cloud edition (for example, the hosted isA cloud). Set your cloud API key, then install and start:

export ISA_API_KEY=YOUR_API_KEY      # copy the complete key from Console
./install.sh --mode edge
isa-mate serve

Edge selects its cloud edition the same way standalone selects a provider — via isa-mate init / the installer’s mode flags — and defaults to the hosted isA cloud gateway when no other edition is configured. An on-prem or customer-hosted edition remains selectable for deployments that need one.

Selecting the mode in the web client

The web client (isA_) reads its runtime mode from an environment variable at build/deploy time:

# .env — one of: local, edge, cloud (legacy: local_standalone, local_edge, hosted_saas)
NEXT_PUBLIC_RUNTIME_MODE=cloud

An unset or unrecognized value falls back to cloud, the hosted default. See .env.example in the isA_ repo for the full list of runtime environment variables.

Next steps

  • Getting Started — install the Agent SDK and make your first call
  • isA Mate — the local-first agent app that powers local and edge execution
  • Architecture — how platform components fit together
Home