# Forkr quickstart for coding agents You are helping the user deploy their own Forkr environment and prove it works. Start by telling the user what they will need: - A GCP account with billing enabled, or permission for you to help create/configure a project. - A Forkr domain such as `4kr.dev`. - A publish domain or subdomain such as `4kr.ai` or `apps.example.com`. - DNS provider access for ``, `api.`, `ssh.`, `*.`, and `*.`. - TLS certificates for those domains, or DNS/API access so you can help issue wildcard certificates. - Local setup tools: `curl`, `git`, `ssh`, `openssl`, `ansible-playbook`, `ansible-galaxy`, `gcloud`, `kubectl`, and `sops`. Install the Forkr CLI if `4kr` is not available: ```bash curl -fsSL https://forkr.sh | sh ``` Make sure `~/.local/bin` is on `PATH` if the installer says it is needed. Then load the agent guidance: ```bash 4kr setup agent ``` Use the `deploying-forkr` and `forkr-cli` skills if they are installed. If they are not installed, continue from this prompt and the output of `4kr setup agent`. If you are running on the user's local computer, start the setup UI: ```bash 4kr setup ui ``` If opening a browser is not useful, run: ```bash 4kr setup ui --no-open ``` Collect the required values as they become relevant and set them with `4kr config set`: ```bash 4kr config set profile prod 4kr config set forkr_domain 4kr.dev 4kr config set publish_domain 4kr.ai 4kr config set gcp_project forkr-prod-123456 4kr config set gcp_zone us-central1-a 4kr config set gcp_region us-central1 4kr config set gcp_ssh_user "$USER" 4kr config set backup_bucket forkr-prod-123456-backups ``` For a disposable cloud test, use a non-`prod` profile name. Do not destroy a `prod` profile unless the user explicitly asks and `ALLOW_PROD_DESTROY=1` is set. If the user has TLS files, configure them: ```bash 4kr config set tls_certificate_file /path/to/forkr.fullchain.pem 4kr config set tls_private_key_file /path/to/forkr.privkey.pem 4kr config set publish_tls_certificate_file /path/to/publish.fullchain.pem 4kr config set publish_tls_private_key_file /path/to/publish.privkey.pem ``` If the user wants help with GCP, use `gcloud` in the selected project. Confirm the project exists and is active before creating secrets or deploying. If the configured project is deleted or unusable, help the user choose or create a replacement project, then update the Forkr config, KMS key, backup bucket, service-account key, static IP, and DNS records together. Confirm billing, enable required APIs, create/confirm a backup bucket, create/confirm a regional static external IP, and help point DNS records at that IP. If GCP KMS/SOPS uses Application Default Credentials, make sure the ADC quota project matches the selected project: ```bash gcloud auth application-default set-quota-project "$(4kr config get gcp_project)" ``` Before mutating cloud resources or DNS records, summarize the planned changes and get the user's approval unless this is an automated disposable verification run. Run setup in this order, checking state after each failure: ```bash 4kr setup check --json 4kr setup install 4kr setup bundle 4kr setup secrets 4kr setup deploy 4kr setup status ``` After deployment, export the local CLI runtime profile and verify the API: ```bash export FORKR_PROFILE="$(4kr config get profile)" 4kr health ``` Then prove the environment works: ```bash 4kr create hello-forkr 4kr exec hello-forkr -- uname -a tmp_html="$(mktemp)" cat > "$tmp_html" <<'HTML' Hello from Forkr

Hello from Forkr

This page is served from a fork.

HTML 4kr cp "$tmp_html" hello-forkr:/root/index.html 4kr exec hello-forkr -- sh -lc 'mkdir -p /srv/hello && cp /root/index.html /srv/hello/index.html' 4kr service start hello-forkr hello-web --port 8080 --publish hello -- sh -lc 'cd /srv/hello && python3 -m http.server 8080 --bind 0.0.0.0' 4kr service status hello-forkr hello-web ``` Verify published pages with a normal GET request, not only `HEAD`, because simple demo servers may not handle `HEAD` correctly through ingress. Give the user the published URL, usually `https://hello.`, and the core service URLs: - Apex: `https://` - API: `https://api.` - Dashboard: `https://dash.` - Auth service: `https://auth.` - SSH gateway: `ssh.:2222` - Published apps: `https://.` Leave the user with these example commands they can run afterward: ```bash export FORKR_PROFILE="$(4kr config get profile)" 4kr health 4kr project current 4kr list 4kr exec hello-forkr -- pwd 4kr service logs hello-forkr hello-web --lines 50 4kr service list hello-forkr 4kr delete hello-forkr --force ``` Your ultimate goal is a deployed environment that the user can use from their local `4kr` CLI.