GitHub - futuregene/future-os: One AI agent, everywhere you work — terminal, desktop, mobile, and your chat apps. Rust core.

One AI agent, everywhere you work.

Terminal, desktop, mobile, and your chat apps — one Rust core, one agent.
Configurable approvals and OS sandboxes. Local-first. Open source.

Quick Start • Features • Models • Commands • Troubleshooting

⭐ If FutureOS is useful to you, a star helps others find it.

Why FutureOS

• Choose the execution boundary. Configure file-access approvals and OS sandboxing for agent tools. The desktop defaults to Unrestricted (off); select Manual or Sandboxed before working with untrusted content. See the security model and sandbox guide for defaults and limitations.
• One backend, every surface. A single gRPC agent drives the terminal UI, desktop app, mobile apps, CLI, and IM bots — same sessions, same memory, same skills, wherever you happen to be.
• Long runs need engineering, not prompting. The built-in goal control plane gives durable goals, event-sourced state, and verification gates to runs of 24+ hours — start a research task at night, review the results from your phone in the morning.

Features

Quick Start

Install

One line, no source build required:

macOS / Linux — one script, auto-detects the platform: macOS gets the official signed app (arm64 / Intel); Linux gets the .deb on Debian/Ubuntu (desktop app + unified future CLI) or the portable tarball everywhere else:

curl -fsSL https://dl.future-os.cn/install.sh | bash

Windows (PowerShell) — runs the signed installer silently:

iex (irm https://dl.future-os.cn/install.ps1)

Step-by-step installation for every platform (desktop app, toolchains, GUI packaging) is in the Build & Install guide.

The installers finish by running future init.

Configure a model

The agent needs at least one model provider before it can answer. The interactive setup supports both FutureOS and custom providers:

FutureOS hosted models — device-flow sign-in provisions keys and a model list automatically:

This works whether or not the agent is running: with the agent up the key is applied live; without it the key is written to ~/.future/agent/auth.json and picked up when the agent starts.

{
  "openai": { "type": "api_key", "key": "sk-..." }
}

{
  "azure": { "type": "api_key", "key": "sk-...", "baseUrl": "https://my-resource.openai.azure.com/openai/v1" }
}

{
  "providers": {
    "my-provider": {
      "apiKey": "sk-...",
      "baseUrl": "https://my-api.example.com/v1",
      "models": [
        { "id": "my-model", "name": "My Model", "contextWindow": 128000, "maxTokens": 16384 }
      ]
    }
  }
}

Install skills (optional)

Skills are add-on capability packs the agent picks up from ~/.future/agent/skills/. Browse the catalog and install what you need — this only needs network access, not a running agent:

future skills list             # browse the skill catalog
future skills install <name>   # install one skill
future skills install          # no name: install every built-in skill

Skip this and the agent still answers fine — skills just add ready-made workflows. uninstall / update and friends are in the CLI reference.

Run the agent

The terminal and CLI clients are thin gRPC clients. They connect over per-user local IPC by default (a Unix-domain socket on macOS/Linux, a current-user-only named pipe on Windows). Unix honors FUTURE_AGENT_SOCKET; otherwise the endpoint always lives under the instance's FutureOS home: ~/.future/run/agent.sock by default, <FUTURE_HOME>/run/agent.sock for an instance started with its own home (future agent --home DIR) — see isolated instances. If the FutureOS home sits on a filesystem that cannot host Unix sockets (e.g. NFS), point FUTURE_HOME at a directory on a local filesystem. Desktop GUI/headless first attach to a compatible external Agent; when the default endpoint is absent and its instance lock is free, they run the complete Agent in their own process. Incompatible or locked/unavailable services produce an error without starting a second Agent. The TUI retains its independent Agent startup. You can also start an external Agent yourself:

future agent     # start the agent in the terminal (logs to stdout; Ctrl-C to stop)

Quitting an embedded Desktop stops work from every connected client, including CLI/TUI conversations. An attached external Agent stays running; Desktop cancels its own submitted runs. See Desktop Agent lifecycle and recovery.

Then launch the terminal UI from the same future command:

Published builds check for updates once in the background after TUI startup. A newer version is shown as a local notice with the official installer link; nothing is installed automatically. Release builds check the release channel, and test/nightly builds check nightly. Local/source builds skip the check. Network failures are silent; future tui --offline disables the check, and non-interactive commands never perform it.

Remote / development mode: pass --grpc-addr 127.0.0.1:50051 to future agent to serve plain TCP instead, and point clients at it with FUTURE_AGENT_GRPC_ADDR=127.0.0.1:50051. TCP is opt-in — never expose it beyond a trusted interface.

future <cmd> is the unified entry point for every Rust component: future agent, future tui, future channel, future goal. Each runs the same code as the standalone binary of the same name (the future-* binaries still exist as build targets — cargo build -p future-tui etc. — but are no longer installed by default).

If connection fails, check Agent discovery, compatibility and instance ownership — see Troubleshooting.

Essential Slash Commands (TUI)

Run /help in the TUI for the full list (40+ commands).

Keyboard Shortcuts (TUI)

Troubleshooting

Community

💬 Discussions • 🐛 Issues • 🔒 Security • 📖 Wiki • Third-Party Notices