brasse/agent-helm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Wiki: dela i två perspektiv — Anslut (befintlig server) + Self-hosting (egen infra) 

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bjorn Blomberg
2026-06-28 18:17:34 +02:00
parent 0bf74eec03
commit 969aee4762
3 changed files with 174 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
Anslut.md Normal file

@@ -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=<din 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`.

117
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=<din hemliga 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).

72
Self-hosting.md Normal file

@@ -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=<din token>`, `PORT=8787`, `DATA_DIR=/app/data`
- `expose: 8787` (ingen host-port — reverse proxyn binder publikt)
- volym: `<host-katalog>:/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.