Sett opp cplt i et repo

Første gang i et repo

Uten egen konfig slipper cplt agenten til prosjektkatalogen og de offentlige pakkeregistrene. Docker og filene med tokenene dine er stengt, og på macOS også localhost. Det repoet trenger i tillegg, skriver teamet i .cplt.toml i roten av repoet.

Start med å se hva cplt init foreslår. Uten flagg skriver den ingenting:

cplt init

Se over forslaget. Under [propose] står det som åpner sandkassen. Linjer som er kommentert ut, peker på filer i hjemmekatalogen din og hører hjemme i din egen konfig, ~/.config/cplt/config.toml, ikke i repoet. cplt init finner ikke alt. Sammenlign med tabellen under.

Er forslaget riktig, skriv fila, sjekk den inn og godkjenn den:

cplt init --write
git add .cplt.toml
git commit -m "chore: add cplt sandbox config"
cplt trust accept --all

cplt leser fila slik den er i siste commit, så agenten kan ikke gi seg selv mer midt i en økt. Hver utvikler godkjenner forslaget på sin egen maskin med cplt trust accept. cplt trust show viser hva som er godkjent, og hva som venter.

Har repoet allerede en .cplt.toml, legg til én nøkkel om gangen, eller ta med det init finner nå:

cplt config set --repo allow.localhost 5432   # legger forslaget i .cplt.toml     
cplt init --write --merge                     # legger til nye funn, fjerner ingenting

Det stakken din trenger

Feilen du ser i sandkassen på macOS, og hva du skriver i .cplt.toml. localhost står under [propose.allow], de andre nøklene under [propose]. Feilmeldingene lenker til oppslaget i Feil i sandkassen.

En Kotlin-app med Gradle, MockK og PostgreSQL i Docker Compose får denne fila:

[propose]
allow_localhost_any = true   # Gradle-daemonen, httptest og Turbopack bruker tilfeldige porter
allow_jvm_attach = true      # MockK

[propose.allow]
localhost = [5432]           # PostgreSQL fra docker compose

Hvorfor noen stakker trenger alle portene, står under Tjenester på localhost.

Tjenester på localhost

På macOS stenger cplt localhost. Agenten kan starte en utviklingsserver, og du når den fra nettleseren som vanlig, men agenten selv når ikke tjenester på din maskin. Har tjenesten fast port, som en database, åpne bare den:

cplt config set allow.localhost 5432

Go-tester med httptest, Gradle-daemonen og arbeidsprosessene til Turbopack, Vite og esbuild lytter på tilfeldige porter, så én port er ikke nok. Med bare port 3000 åpen starter Next.js, men første side feiler. Da må du åpne alle portene:

cplt config set sandbox.allow_localhost_any true

• Med allow_localhost_any når agenten alle tjenester som lytter på localhost, også en lokal database.
• På Linux koster den mer: kjernen der kan ikke skille localhost fra andre hoster, så cplt slår av portfiltreringen for utgående TCP helt, og bare proxyen begrenser hvor agenten kan koble seg til.
• Med proxy.forced slått på, som i --preset strict, ser cplt bort fra allow_localhost_any. Enkeltporter fra allow.localhost virker fortsatt, men tilfeldige porter kan ikke åpnes. Da må du kjøre uten tvungen proxy.

Skal hele teamet ha innstillingen, bruk cplt config set --repo … og sjekk inn .cplt.toml, som beskrevet i Første gang i et repo.

Pakker fra GitHub Packages

@navikt-pakker på npm og Maven ligger i GitHub Packages, og der må du logge inn. Tokenet ligger i ~/.npmrc, ~/.gradle/gradle.properties eller ~/.m2/settings.xml. cplt stenger disse filene, så npm install svarer 401 Unauthorized og Gradle finner ikke pakken. På Linux er bare ~/.npmrc stengt. De to andre ligger i mapper agenten har tilgang til. cplt init advarer om dette når .npmrc i repoet henter pakker fra GitHub Packages.

For npm og pnpm er det enklest å installere utenfor cplt før du starter agenten:

pnpm install        # i terminalen, utenfor cplt
nav-pilot

Må agenten hente pakker selv, gi den lesetilgang til de tre filene:

cplt config set sandbox.allow_build_credentials true --force

Da kan agenten lese alle tokenene i filene, ikke bare det prosjektet trenger. Derfor krever cplt --force, og derfor kan ikke nøkkelen stå i .cplt.toml. Bruk et token som bare kan lese pakker (read:packages). Trenger du bare én av filene, gi lesetilgang til den, for eksempel cplt config set allow.read ~/.gradle/gradle.properties.

Under en liste over tillatte hoster når Copilot npm.pkg.github.com og maven.pkg.github.com, fordi lista har med github.com og alle subdomenene. Får du 401, har forespørselen kommet fram. Da er det tokenet som mangler, ikke nettverket.

Hvert verktøy har sin egen vei rundt dette: npm kan lese tokenet fra en miljøvariabel, pnpm og yarn 1 trenger ~/.npmrc, og Gradle kan hente fra Navs speil uten token. Se Node, npm og pnpm og Kotlin og Gradle.

Pakkeregistre og en liste over tillatte hoster

I standardoppsettet stopper cplt bare kjente skadelige hoster og hoster med private adresser, og installasjoner virker som vanlig. Har du slått på en liste over tillatte hoster, med --preset strict, proxy.default_allowlist eller proxy.allowed_domains, slipper cplt bare gjennom det som står på lista. Pakkeregistrene er med når proxy.default_allowlist er på, og strict slår den på. Med bare proxy.allowed_domains er de med hvis fila lister dem. Fila nav-pilot skriver, har alle når cplt støtter cplt config hosts. Er cplt for gammel til det, mangler Gradle-plugin-artefaktene, Confluent og JitPack:

• registry.npmjs.org og registry.yarnpkg.com (npm og yarn)
• repo.maven.apache.org (Maven Central)
• plugins.gradle.org og plugins-artifacts.gradle.org (Gradle-plugins)
• crates.io og static.crates.io (Cargo)
• pypi.org og files.pythonhosted.org (PyPI)
• packages.confluent.io og jitpack.io

Mangler en host, sjekk den og legg den til med allow.domains. Den legger til på en liste som allerede er slått på, og slår ikke på lista selv:

cplt check net min.vert.no
cplt config set allow.domains min.vert.no

pnpm

I sandkassen legger pnpm lageret i repoet, i .pnpm-store/ eller node_modules/.pnpm-store/, og laster ned alle pakkene på nytt i hvert repo og hvert worktree. Årsaken er at pnpm vil lage en mappe i $PNPM_HOME, der agenten ikke får skrive (cplt#637). Pek pnpm på det felles lageret, her på macOS:

export pnpm_config_store_dir=$HOME/Library/pnpm/store   # i skallet, for eksempel ~/.zshrc
cplt config set sandbox.pass_env pnpm_config_store_dir   # send den inn i sandkassen

Ellers legger du lageret i .gitignore:

echo ".pnpm-store/" >> .gitignore

Skript som kjører når en pakke installeres, er slått av i sandkassen for npm, pnpm og yarn 1 (ikke yarn 2 og nyere), se Skript som kjører ved installasjon.

mise

Verktøy mise allerede har installert, kan agenten bruke, og mise run virker. Mangler en versjon, stopper mise med denne feilen:

failed create_dir_all ~/.local/share/mise/installs/…: Operation not permitted

Det er med vilje. Et program agenten laster ned og kjører selv, kan gjøre det sandkassen ellers stopper. Installer utenfor cplt før du starter agenten:

mise install

cplt init minner deg om dette når repoet har en mise-konfig med [tools]. cplt doctor gjør det samme når en versjon mangler.

Docker

Docker er stengt i sandkassen. Den som kan snakke med Docker-daemonen, kan starte en container som monterer hele disken, og da er sandkassen borte. Det gjelder også Testcontainers, se Testcontainers og Docker.

cplt init foreslår allow_docker når repoet har en compose-fil. Ta den ut av forslaget. For en Dockerfile alene foreslår den ikke Docker, men advarer om at docker build ikke virker i sandkassen. I Nav bygger CI-en imagene, så agenten trenger ikke Docker. Start tjenestene selv i en egen terminal, og åpne portene agenten skal nå:

docker compose up -d                         # i en terminal utenfor cplt
cplt config set --repo allow.localhost 5432   # agenten når databasen på localhost

Brytere for hele maskinen

Det som gjelder alle repoene dine, hører hjemme i din egen konfig, ~/.config/cplt/config.toml. nav-pilot config sandbox viser bryterne for hele maskinen, for eksempel localhost og Docker, og skriver dit. Det samme gjør cplt config set:

nav-pilot config sandbox
cplt config set sandbox.allow_localhost_any true

Sikkerhetsnivået setter du med nav-pilot config, se Sandkassen. Får du en feil du ikke finner her, slå den opp i Feil i sandkassen.