diff --git a/Anslut.md b/Anslut.md new file mode 100644 index 0000000..f1e1d0f --- /dev/null +++ b/Anslut.md @@ -0,0 +1,85 @@ +# Anslut till en befintlig server + +Det här är vägen när **servern redan är uppsatt** (t.ex. `wss://rcai.brasse-pc.eu`) och du +**känner din token**. Du behöver bara webb-UI:t och en klient. + +> Vill du istället sätta upp allt själv? Se **[Hosta själv](Self-hosting)**. + +## 1. Webb-UI:t (mobil eller dator) + +Öppna serverns adress i webbläsaren (t.ex. `https://rcai.brasse-pc.eu`) och logga in med +din **token**. + +- Till vänster: alla anslutna sessioner. Välj en → du ser dess terminal live. +- **Fallback-tangentbord** längst ned: `← ↑ ↓ →`, `Enter`, `Esc`, `Tab`, `Ctrl-C`, `y`/`n`. + Det funkar alltid — även utan hooks. +- **Godkännande-kort:** om verktygsgodkännanden är på dyker agentens verktygsanrop upp + som kort med **Tillåt / Neka**. + +## 2. Installera klienten (Linux, x86_64 eller arm64) + +Ett kommando — självständig binär, inga beroenden på målet: + +```bash +curl -fsSL https://gitea.brasse-pc.eu/brasse/agent-helm/raw/branch/main/install.sh | sh +``` + +- System-wide (`/usr/local/bin`): kör med `| sudo sh`. +- Annars hamnar `agent-helm` i `~/.local/bin` — ha den katalogen i din `PATH`. +- Samma kommando på Arch, Ubuntu m.fl. Uppdatera senare: kör det igen. + +## 3. Konfigurera och anslut + +Fyll i `~/.config/agent-helm/config.env`: + +```ini +AGENT_HELM_TOKEN= +SERVER_URL=wss://rcai.brasse-pc.eu +AGENT_CMD=gemini +# AGENT_CWD=/sökväg/till/projekt +``` + +Starta klienten: + +```bash +# som bakgrundstjänst (rekommenderas): +systemctl --user daemon-reload && systemctl --user enable --now agent-helm +# eller direkt: +set -a; . ~/.config/agent-helm/config.env; agent-helm +``` + +→ **din session dyker upp i webb-UI:t.** Öppna den på mobilen och styr agenten. + +## Var lagras din token? + +Bara i `~/.config/agent-helm/config.env` (rättigheter `600`) på din maskin. Det är det +enda som ger åtkomst till sessionerna — **håll den hemlig**. Tappar du den eller vill byta: +be den som driftar servern om en ny token och uppdatera din `config.env`. + +## Verktygsgodkännanden (valfritt) + +Vill du godkänna agentens verktygsanrop från mobilen? Lägg en `BeforeTool`-hook i +`~/.gemini/settings.json` på klientmaskinen: + +```json +{ + "hooks": { + "BeforeTool": [ + { "hooks": [{ "type": "command", "command": "agent-helm hook" }] } + ] + } +} +``` + +Då visas varje verktygsanrop som ett kort i UI:t. Utan hook fungerar allt ändå. + +## Felsökning + +| Problem | Trolig orsak | +|---|---| +| UI:t laddar men inga sessioner | Ingen klient ansluten, fel token, eller fel `SERVER_URL` | +| Klienten ansluter inte | Kontrollera token, `SERVER_URL=wss://…`, och nätet | +| `agent-helm: command not found` | Lägg `~/.local/bin` i din `PATH` (eller installera system-wide) | +| Inga godkännande-kort | Hooken är inte uppsatt (valfritt) | + +Tjänstens loggar: `journalctl --user -u agent-helm -f`. diff --git a/Home.md b/Home.md index b964a0c..dac2c86 100644 --- a/Home.md +++ b/Home.md @@ -1,109 +1,26 @@ # agent-helm -Kör dina CLI-agenter (Gemini) på valfri maskin och **styr dem från mobil eller webb** — -live-terminal, fallback-tangentbord och (valfritt) godkännande-kort för verktygsanrop. +Kör CLI-agenter (Gemini) på valfri maskin och **styr dem från mobil eller webb** — +live-terminal, fallback-tangentbord och valfria godkännande-kort för verktygsanrop. -> Den här sidan är skriven ur användarens perspektiv: hur du sätter upp det, kör -> klienten, var nycklar lagras och hur du ansluter. +## Välj din väg ---- +- **[Anslut till en befintlig server](Anslut)** — servern är redan uppsatt och du + känner din token. Du vill bara installera klienten och koppla upp. +- **[Hosta själv](Self-hosting)** — sätt upp hela stacken (server, reverse proxy och + ev. CI) på din egen infrastruktur. -## Snabbstart (3 steg) +## Arkitektur i korthet -1. **Öppna webb-UI:t:** [`https://rcai.brasse-pc.eu`](https://rcai.brasse-pc.eu) och logga in med din token. -2. **Installera klienten** på maskinen där agenten ska köra (se nedan). -3. **Sätt token + starta klienten** → sessionen dyker upp i UI:t, redo att styras. - ---- - -## 1. Webb-UI:t (mobil eller dator) - -- Adress: `https://rcai.brasse-pc.eu` -- Logga in med din **token** (samma som klienterna använder). -- Till vänster: alla anslutna sessioner. Välj en → du ser dess terminal live. -- **Fallback-tangentbord** längst ned: `← ↑ ↓ →`, `Enter`, `Esc`, `Tab`, `Ctrl-C`, `y`/`n`. - Det funkar alltid — även om inga hooks är uppsatta. -- **Godkännande-kort:** om verktygsgodkännanden är på (se längre ned) dyker - agentens verktygsanrop upp som kort med **Tillåt / Neka**. - -## 2. Installera klienten (Linux, x86_64 eller arm64) - -Ett kommando — laddar ner rätt binär (Node + allt inbäddat, inga beroenden): - -```bash -curl -fsSL https://gitea.brasse-pc.eu/brasse/agent-helm/raw/branch/main/install.sh | sh +``` +klient/daemon (kör agenten i en pty) ──wss──► server ◄──wss── webb / mobil + node-pty( gemini ) (control-plane + web-UI) (xterm.js + kort) + │ + reverse proxy (TLS + WebSockets) ``` -- System-wide (i `/usr/local/bin`): kör med `| sudo sh` istället. -- Annars hamnar den i `~/.local/bin` — se till att den katalogen ligger i din `PATH`. -- Fungerar lika på Arch, Ubuntu m.fl. — binären är självständig. +- **Server** — en container, token-autentiserad, serverar web-UI:t + WebSocket på samma port. +- **Klient** — självständig binär (Linux x64/arm64) som kör agenten och strömmar till servern. +- **Token** — en delad hemlighet som skyddar all åtkomst. Lagras hos server + klient, **aldrig i git**. -Uppdatera senare: kör samma kommando igen. För en specifik version: -`AGENT_HELM_VERSION=v0.1.1 curl ... | sh`. - -## 3. Konfigurera och anslut - -Installern skapar `~/.config/agent-helm/config.env`. Fyll i: - -```ini -AGENT_HELM_TOKEN= -SERVER_URL=wss://rcai.brasse-pc.eu -AGENT_CMD=gemini -# AGENT_CWD=/sökväg/till/projekt -``` - -Starta klienten: - -```bash -# som bakgrundstjänst (rekommenderas): -systemctl --user daemon-reload && systemctl --user enable --now agent-helm - -# eller direkt i terminalen: -set -a; . ~/.config/agent-helm/config.env; agent-helm -``` - -Klienten ansluter till servern och **din session dyker upp i webb-UI:t**. Öppna den -på mobilen och styr agenten. - ---- - -## Var lagras nycklar och hemligheter? - -- **Token** (det enda som skyddar åtkomsten till dina sessioner) lagras: - - på **klienten** i `~/.config/agent-helm/config.env` (filrättigheter `600`), - - på **servern** i dess konfiguration (på Pi5). -- Den finns **aldrig** i git-repot eller någon publik fil. -- Samma token måste användas av både webb-UI:t och klienterna för att de ska få ansluta. -- **Håll token hemlig.** Vill du byta/rotera den: uppdatera den på servern och i varje - klients `config.env`, och starta om. - -## Verktygsgodkännanden (valfritt) - -Vill du godkänna agentens verktygsanrop från mobilen? Lägg till en `BeforeTool`-hook i -`~/.gemini/settings.json` på klientmaskinen: - -```json -{ - "hooks": { - "BeforeTool": [ - { "hooks": [{ "type": "command", "command": "agent-helm hook" }] } - ] - } -} -``` - -Då visas varje verktygsanrop som ett kort i UI:t (Tillåt/Neka). Utan hook fungerar allt -som vanligt — agenten kör på, och du styr via terminalen/fallback-tangentbordet. - ---- - -## Felsökning - -| Problem | Trolig orsak | -|---|---| -| UI:t laddar men inga sessioner | Ingen klient ansluten, fel token, eller fel `SERVER_URL` | -| Klienten ansluter inte | Kontrollera token, att `SERVER_URL=wss://rcai.brasse-pc.eu`, och nätet | -| `agent-helm: command not found` | Lägg `~/.local/bin` i din `PATH` (eller installera system-wide) | -| Inga godkännande-kort | Hooken är inte uppsatt i `~/.gemini/settings.json` (valfritt) | - -Loggar för tjänsten: `journalctl --user -u agent-helm -f`. +Källkod: [`brasse/agent-helm`](https://gitea.brasse-pc.eu/brasse/agent-helm). diff --git a/Self-hosting.md b/Self-hosting.md new file mode 100644 index 0000000..3db1c25 --- /dev/null +++ b/Self-hosting.md @@ -0,0 +1,72 @@ +# Hosta själv + +Sätt upp hela agent-helm på **din egen infrastruktur**. Guiden är generisk — anpassa +registry, reverse proxy och CI till din stack. (Den fullständiga referens-uppsättningen +med Pi5 + Dockge + Nginx Proxy Manager finns i repots +[`deploy/DEPLOY.md`](https://gitea.brasse-pc.eu/brasse/agent-helm/src/branch/main/deploy/DEPLOY.md).) + +> Vill du bara koppla upp mot en server som redan finns? Se **[Anslut](Anslut)**. + +## Du behöver + +- En **Docker-host** för servern. +- En **reverse proxy** med TLS **och WebSocket-stöd** (Nginx Proxy Manager, Caddy, + Traefik …) samt ett domännamn. +- *(Valfritt)* en **container-registry** och **Gitea Actions** för automatiska byggen. + +## 1. Token (gör först) + +Generera en stark slumpad hemlighet. Den är **enda** åtkomstgrinden till sessionerna. +Lägg den i serverns miljö och i varje klients config — **aldrig i git**. + +## 2. Servern + +Bygg image:n från repots `Dockerfile` (eller via CI, se steg 5) och kör den. Det finns en +färdig compose i `deploy/agent-helm.compose.yaml`: + +- env: `AGENT_HELM_TOKEN=`, `PORT=8787`, `DATA_DIR=/app/data` +- `expose: 8787` (ingen host-port — reverse proxyn binder publikt) +- volym: `:/app/data` — skapa den **före** start och äg den som **uid 1000** + (containern kör som uid 1000), annars kan appen inte skriva. Hit hamnar framtida db/auth. + +Servern serverar den inbyggda web-frontenden **och** WebSocket på samma port. + +## 3. Reverse proxy + +Peka din domän → `agent-helm:8787`. **Slå på WebSocket-stöd** (annars laddar UI:t men +sessioner kopplar aldrig upp) och TLS (t.ex. Let's Encrypt). Klienterna ansluter sedan +till `wss://din-domän`. + +## 4. Klienterna + +Bygg klient-binärerna (repots `release`-workflow, eller `pkg` lokalt) och installera dem +med `install.sh`. Peka klientens `SERVER_URL` på din domän. Binären är självständig +(Node + node-pty inbäddat) för linux x64/arm64. + +## 5. CI (valfritt men rekommenderat) + +Repot innehåller två Gitea Actions-workflows: + +- `.gitea/workflows/build.yaml` — på push till `master`: bygger **server-image** och + pushar till din registry. +- `.gitea/workflows/release.yaml` — på push till `master`: bygger **klient-binärer** + (x64 + arm64 med `pkg --no-bytecode`, så de cross-byggs utan QEMU) och publicerar dem + som en rullande `latest`-release. `vX.Y.Z`-taggar ger versionerade releaser. + +Det kräver en **Gitea Actions-runner i Docker** (`deploy/act-runner.{compose,config}.yaml`). +Runnern monterar värdens docker.sock och bygger nativt — kör den på en arm64-host om du +vill ha arm64-images. Se `deploy/DEPLOY.md` för registrering och fallgropar. + +## Strukturerade godkännanden (hook) + +Klienten kan ta emot verktygsgodkännanden via en `BeforeTool`-hook (`agent-helm hook`). +Hooken pratar med daemonen över en endpoint som binder **endast `127.0.0.1`** — aldrig +nåbar utifrån. Utan UI faller den tillbaka till `AGENT_HELM_HOOK_DEFAULT` (default `allow`). + +## Säkerhet + +- **Token = enda åtkomstgrinden.** Håll den hemlig, rotera vid läcka (byt på server + + klienter). Lägg den aldrig i git — använd serverns/klientens lokala konfiguration. +- Exponera bara via reverse proxyn (TLS). Ingen rå host-port behövs. +- Hook-endpointen är loopback-only. +- Om din registry saknar auth: håll den LAN-only.