{"id":51559460,"url":"https://github.com/autonomous-ai/autonomous-grid","last_synced_at":"2026-07-10T09:02:43.648Z","repository":{"id":365461997,"uuid":"1271836518","full_name":"autonomous-ai/autonomous-grid","owner":"autonomous-ai","description":"Grid is the orchestration layer for local AI. It pools the computers you already own to run AI inference.","archived":false,"fork":false,"pushed_at":"2026-07-07T04:59:12.000Z","size":3086,"stargazers_count":62,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-07T06:23:42.575Z","etag":null,"topics":["ai","homelab","inference","llm","local-llm","openai-compatible","orchestration","python","self-hosted"],"latest_commit_sha":null,"homepage":"https://www.autonomous.ai/grid","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/autonomous-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-17T03:56:36.000Z","updated_at":"2026-07-07T04:39:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/autonomous-ai/autonomous-grid","commit_stats":null,"previous_names":["autonomous-ai/autonomous-grid"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/autonomous-ai/autonomous-grid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autonomous-ai%2Fautonomous-grid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autonomous-ai%2Fautonomous-grid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autonomous-ai%2Fautonomous-grid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autonomous-ai%2Fautonomous-grid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/autonomous-ai","download_url":"https://codeload.github.com/autonomous-ai/autonomous-grid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autonomous-ai%2Fautonomous-grid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35326963,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-10T02:00:06.465Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","homelab","inference","llm","local-llm","openai-compatible","orchestration","python","self-hosted"],"created_at":"2026-07-10T09:02:42.997Z","updated_at":"2026-07-10T09:02:43.642Z","avatar_url":"https://github.com/autonomous-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# ⚡ Grid\n\n### Orchestrate the computers you already own to run AI inference.\n\n[![CI](https://github.com/autonomous-ai/autonomous-grid/actions/workflows/ci.yml/badge.svg)](https://github.com/autonomous-ai/autonomous-grid/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)\n\n[**Quickstart**](#quickstart) · [Two modes](#two-modes) · [How it works](#how-it-works) · [CLI reference](docs/cli.md) · [Contributing](#contributing)\n\n\u003cimg src=\"docs/home-grid.png\" alt=\"Your Home Grid sits above your computers — OpenClaw, Hermes, and your own apps call one endpoint; Grid routes each request to whichever computer serves the model\" width=\"860\"\u003e\n\n\u003c/div\u003e\n\nGrid pools the computers you already have — your Mac, your NVIDIA desktop, the workstation in the corner — behind **one OpenAI-compatible endpoint**, and routes each request to whichever one is running the right model.\n\nThe inference servers you run (Ollama, vLLM, LM Studio, MLX, llama.cpp, ComfyUI) stay where they are — Grid just ties them together.\n\nRun it on your **local** network, or sign in to reach your computers **remotely** through **Autonomous Relay**, our hosted connection. Same commands, two modes.\n\n## Two modes\n\nGrid runs in one of two **modes**, and the same verbs (`up`, `join`, `chat`, `info`) work in both:\n\n| | **`local`** _(default)_ | **`remote`** |\n|---|---|---|\n| What it is | Unauthenticated, local-only proxy | Signed-in thin client to Autonomous Relay (our hosted connection) |\n| Reach | Same network only | From anywhere |\n| Sign-in | None | `grid login` (your account) |\n| API key | `local-grid` placeholder — auth is off | Your per-grid access token |\n| How requests flow | Engines poll the relay for work; apps consume through it | |\n\nThe chosen mode is persisted to **`~/.grid/state.json`**, and each mode remembers its own active grid there.\nSwitch any time with `grid mode local|remote`, or override a single command with `--local` / `--remote`. A computer\nwith no state file behaves exactly as a `local`-only install.\n\n## Quickstart\n\n**Install** — on each computer (macOS / Linux):\n\n```bash\ncurl -fsSL https://grid.autonomous.ai/install.sh | bash\n```\n\nYou get `grid` (and the `agrid` alias) on your PATH — a self-contained binary on Linux, or a\n[uv](https://docs.astral.sh/uv/)-managed install on macOS. Pin a release with `GRID_VERSION=0.1.0`.\nContributors can instead clone and `uv tool install -e . --force`.\n\nEvery step below gives the **🌐 Remote** command and the **🏠 local** command.\n\n### 1 · Choose your mode\n\n`grid mode` writes your choice to `~/.grid/state.json` and keeps it until you switch again — so the rest of\nyour commands target the same mode without repeating yourself.\n\n**🌐 Remote**\n```bash\ngrid mode remote\n# remote\n# Remote mode: `grid login` to sign in, then `grid up` to bring a remote grid online …\n```\n\n**🏠 local** — the default; a fresh install is already here.\n```bash\ngrid mode local\n# local\n```\n\n### 2 · Sign in\n\n**🌐 Remote** — sign in once with the device-code flow (opens a browser; `--no-browser` prints the code for headless computers):\n```bash\ngrid login\n# To sign in, open this URL and approve with Google:\n#   https://grid.autonomous.ai/login?user_code=ABCD-1234\n#   Code: ABCD-1234\n# Signed in as you@example.com. 2 grid(s) available: research, team.\n# Run `grid use \u003cname\u003e` to pick one.\n```\n\n**🏠 local** — _nothing to do._ The local proxy is unauthenticated, so there is no sign-in — skip to step 3.\n\n### 3 · Bring a grid online\n\n**🌐 Remote** — create (or start) a hosted grid, then make it your active one. Creating needs an explicit name:\n```bash\ngrid up research --type permissioned-public   # --type is optional (this is the default)\ngrid use research\n# grid=research\n# grid_url=https://grid.autonomous.ai/…        ← apps reach the grid here, with your token\n```\n`grid ls` lists the grids your sign-in can reach; `--type permissioned-providers` restricts who may serve to it.\n\nInvite people with `grid members add research \u003cemail\u003e`. See [Members](docs/cli.md#members).\n\n**🏠 local** — bring up the default `home` grid on this computer:\n```bash\ngrid up\n# grid=home\n# grid_url=http://192.168.1.25:8090            ← the one address engines + apps use\n```\n\n### 4 · Add an engine\n\nPoint Grid at an inference server you already run (here, a computer running vLLM to serve `qwen3-coder`), and name it.\n\n**🌐 Remote** — serve your local engine to the remote grid. The engine polls the relay outbound, so `--at` is its address **on this computer** (`localhost`) — no inbound port or public IP needed:\n```bash\ngrid join research --at http://localhost:8000/v1 -m qwen3-coder --name gpu-4090\n# Joining research (pid=12345) — serving the union via the relay.\n# models=qwen3-coder\n```\n\n**🏠 local** — join it to the `grid_url` from step 3. Here `--at` is the engine's **local address** — the grid forwards requests to it, so it must be reachable on your network:\n```bash\ngrid join http://192.168.1.25:8090 --at http://192.168.1.20:8000/v1 -m qwen3-coder --name gpu-4090\n# Joined engine gpu-4090 to http://192.168.1.25:8090 (pid=12345)\n# models=qwen3-coder\n```\n\nAdd as many computers as you like — repeat `grid join` for each MLX, vLLM, or Ollama you run.\n\n\u003e **🌐 Remote tip:** a beefy engine can serve **several requests at once** — pass\n\u003e `--max-concurrency N` to match its batch width (llama.cpp `--parallel`, vLLM `max_num_seqs`),\n\u003e so the relay keeps it fed in parallel instead of one job at a time:\n\u003e ```bash\n\u003e grid join research --at http://localhost:8000/v1 -m qwen3-coder --max-concurrency 4\n\u003e ```\n\u003e See what each engine is serving at with `grid engines`. Defaults to 1 (serial).\n\n### 5 · Use a model\n\nThe same `grid chat` works in both modes — a quick smoke test, and a handy daily command:\n\n**🌐 Remote** — routed through the relay with your access token:\n```bash\ngrid chat -m qwen3-coder \"write a haiku about local GPUs\"\n```\n\n**🏠 local** — routed straight through the local proxy:\n```bash\ngrid chat -m qwen3-coder \"write a haiku about local GPUs\"\n```\n\n\u003e **🏠 local tip:** see every model across every joined computer with `grid models --verbose`:\n\u003e ```text\n\u003e MODEL        ENGINE      WHERE\n\u003e qwen3-coder  gpu-4090    http://192.168.1.20:8000/v1\n\u003e gemma4-31b   mac-studio  http://192.168.1.10:8080/v1\n\u003e ```\n\u003e Two computers, two frameworks — one endpoint serves both. (The same `grid models` and `grid engine ls` now work for remote grids too — `grid models --verbose` shows each model's engine and where it runs.)\n\n### 6 · Point your apps at the grid\n\n`grid info --env` prints copy-pasteable `OPENAI_*` exports for whichever mode you're in:\n\n**🌐 Remote** — the relay base URL and your real per-grid token (the grid must be up):\n```bash\ngrid info --env\n# export OPENAI_BASE_URL=\"https://grid.autonomous.ai/relay/v1\"\n# export OPENAI_API_KEY=\"\u003cyour access token\u003e\"\n```\n\n**🏠 local** — the local endpoint and a placeholder key (auth is off on your local network):\n```bash\ngrid info --env\n# export OPENAI_BASE_URL=\"http://192.168.1.25:8090/v1\"\n# export OPENAI_API_KEY=\"local-grid\"\n```\n\nWire those two values — `OPENAI_BASE_URL` and `OPENAI_API_KEY` — into any OpenAI-compatible client.\nThe examples below use the local values; remote users paste their relay URL and token instead.\n\n**OpenClaw** — add Grid as a provider in `~/.openclaw/openclaw.json` ([docs](https://docs.openclaw.ai/concepts/model-providers)):\n\n```json\n{\n  \"agents\": { \"defaults\": { \"model\": { \"primary\": \"grid/qwen3-coder\" } } },\n  \"models\": {\n    \"providers\": {\n      \"grid\": {\n        \"baseUrl\": \"http://192.168.1.25:8090/v1\",\n        \"apiKey\": \"local-grid\",\n        \"api\": \"openai-completions\",\n        \"models\": [{ \"id\": \"qwen3-coder\", \"name\": \"Qwen3 Coder (via Grid)\" }]\n      }\n    }\n  }\n}\n```\n\n**Hermes** — set the endpoint in `~/.hermes/config.yaml` ([docs](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)):\n\n```yaml\nmodel:\n  provider: custom\n  default: qwen3-coder\n  base_url: http://192.168.1.25:8090/v1\n```\n\n```bash\necho 'OPENAI_API_KEY=local-grid' \u003e\u003e ~/.hermes/.env     # remote: use your access token\n```\n\n**Your own app** — point any OpenAI SDK at the values from `grid info --env`:\n\n```python\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"http://192.168.1.25:8090/v1\", api_key=\"local-grid\")\nclient.chat.completions.create(\n    model=\"qwen3-coder\",                # routed to the 4090 computer automatically\n    messages=[{\"role\": \"user\", \"content\": \"hello\"}],\n)\n```\n\n**That's it.** Every model on every computer answers at one endpoint — on your local network, or remotely. Add another computer anytime with `grid join`.\n\n### No engine on a computer yet?\n\nGrid ships built-in engines — `llama.cpp` for text, ComfyUI for media. Install one, pull a model, then serve it\nwith `grid join --serve`. `grid engine install` and `grid pull` work the same in both modes; only the grid you join\ndiffers (a remote grid **name**, or a local **`grid_url`**).\n\n```bash\ngrid engine install llama.cpp           # install the text engine (both modes)\ngrid pull qwen36-35b-a3b-mtp            # download a text MODEL (see `grid catalog`, or any HF GGUF)\n\ngrid join research --serve qwen36-35b-a3b-mtp                    # 🌐 remote: your grid name\ngrid join http://192.168.1.25:8090 --serve qwen36-35b-a3b-mtp   # 🏠 local: your grid_url\n```\n\nMedia serving (ComfyUI images + video) works in **both modes** — `grid engine install` and\n`grid engine pull` set up the ComfyUI engine the same way; only the grid you join and consume\nfrom differs.\n\n```bash\ngrid engine install comfyui             # install the media engine (both modes)\ngrid engine pull image_generation       # download a media BUNDLE (also: image_editing, i2v)\n```\n\n**🌐 Remote** — serve to your grid by **name** (the engine polls the relay), then `grid image`\nroutes through your active grid:\n```bash\ngrid join research --media --bundle image_generation\ngrid image \"a compact walnut desk beside a sunlit window\"\n```\n\n**🏠 local** — serve to your **`grid_url`**, and point `grid image` at it with `--grid`:\n```bash\ngrid join http://192.168.1.25:8090 --media --bundle image_generation\ngrid image \"a compact walnut desk beside a sunlit window\" --grid http://192.168.1.25:8090   # --grid: use-commands take the grid as a flag (positional = prompt)\n```\n\n### No GPU at all? Join with an API key\n\nNo capable hardware anywhere? A provider can still contribute capacity with just a paid **OpenAI**\naccount. `grid join --api openai` serves OpenAI's models to your grid under your own key — an **API\nengine**, **remote only**. See what a join would serve first (no key, no network call):\n\n```bash\ngrid catalog --api openai\n# Models a `grid join --api openai` would serve (verified 2026-07-08):\n#   openai:gpt-5.5           1,050,000 ctx   tools, vision, json, structured\n#   openai:gpt-5.4-mini        400,000 ctx   tools, vision, json, structured\n#   …\n```\n\nThen join. The key comes from `OPENAI_API_KEY` (or a hidden prompt) — never a command-line flag — and\nis stored `0o600` for later joins; it survives `grid logout` (it's your vendor credential, not your\ngrid sign-in). With no `-m` you serve every whitelisted model your key can see:\n\n```bash\nexport OPENAI_API_KEY=sk-…\ngrid join research --api openai                       # or -m openai:gpt-5.4-mini to narrow\ngrid chat -m openai:gpt-5.4-mini \"hello from the grid\"\n```\n\nRequests to `openai:*` models **leave the grid for OpenAI**, under your key and your own account's\nterms — the `openai:` prefix keeps that visible in every model list. There's no grid-side spend cap;\nput a budget limit on the key's OpenAI project if you want one. Full contract, key store, and rotation\nin [docs/cli.md](docs/cli.md#engines).\n\n## How it works\n\nGrid sits **above** your computers — like an API gateway above your services, or Tailscale above\nyour network. Each computer runs one or more inference servers (an **engine** — Ollama, vLLM, llama.cpp,\nComfyUI); your grid is the one address everything talks through, and your apps draw from it.\n\n- **the grid** — one endpoint that routes each request to a computer serving that model. On your **local** it's a\n  local proxy you create with `grid up`; in **remote** it's a hosted grid on Autonomous Relay you bring up the\n  same way after `grid login`.\n- **engines** — the tools you already run. `grid join` advertises a computer's engines and heartbeats them; Grid\n  never restarts or replaces them. On local they register directly with the grid; in remote they poll the relay\n  outbound for work, so they serve from behind a NAT with no inbound port.\n- **apps** — anything that speaks the OpenAI API. Text on `/v1/chat`, images and video on `/v1/media`.\n\nFull request flow in **[ARCHITECTURE.md](docs/ARCHITECTURE.md)**; the complete command surface — including\nmembership (`grid members`) and remote grid types — in **[docs/cli.md](docs/cli.md)**.\n\n## Contributing\n\nGrid is small and readable by design — clone to PR in minutes.\n\n```bash\ngit clone https://github.com/autonomous-ai/autonomous-grid\ncd autonomous-grid\nuv sync --extra dev\nuv run --extra dev pytest\n```\n\nGood first PRs: add a model to the catalog (`shared/models/catalog.py`) or a media bundle\n(`shared/models/media_bundles.py`). Start with **[CONTRIBUTING.md](docs/CONTRIBUTING.md)** and\n**[ARCHITECTURE.md](docs/ARCHITECTURE.md)**.\n\nLocal state lives under `~/.grid` (override with `GRID_HOME`).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautonomous-ai%2Fautonomous-grid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fautonomous-ai%2Fautonomous-grid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautonomous-ai%2Fautonomous-grid/lists"}