Skip to content

AI agents and the Falak skill

The Falak skill is an Agent Skill: a SKILL.md with instructions, plus reference files, that teach an AI coding agent (Claude Code, Codex, Cursor and other tools that read SKILL.md) to operate Falak through the falak CLI, falak.yaml and the REST API. It covers deploys and rollbacks, config as code, secrets, functions, database containers, templates, logs, consoles and network tools, and says which actions need a human’s confirmation. It shipped with v0.19.0.

falak/
├── SKILL.md # when to use it, ground rules, core workflows (loaded when the skill triggers)
└── references/
├── cli.md # every falak command, flag, default and exit code
├── config.md # the falak.yaml schema (v1), condensed
├── api.md # tokens, abilities, the main /api/v1 endpoints
├── workflows.md # recipes: repo, template, databases, functions, secrets, domains, logs, consoles, net
├── safety.md # destructive actions, secret handling, least-privilege tokens
└── llms.txt # a short index for tools that read llms.txt

The agent reads SKILL.md when a task mentions Falak, and opens a reference file only when it needs it. The skill does not administer the control plane host itself: that is falak-ctl, run as root on the host.

The falak CLI ships a copy of the skill and writes it for you (falak help lists skill install; run falak update first if it doesn’t):

Terminal window
falak skill install # ~/.claude/skills/falak (your user, every project)
falak skill install --project # .claude/skills/falak in the current directory (commit it for your team)
falak skill install --dir ~/.codex/skills/falak # any other agent's skills folder

It refuses to overwrite existing files; --force replaces them, so run it again after falak update to refresh the skill. --json prints the directory and the files written. --user is the default.

  • Claude Code loads skills from ~/.claude/skills/<name>/SKILL.md and .claude/skills/<name>/SKILL.md. Start a new session after installing.
  • Codex and other SKILL.md tools: put the same folder in the tool’s skills directory (for Codex CLI, ~/.codex/skills/ at the time of writing; check your tool’s docs), or use falak skill install --dir.
  • Tools without skill support (Cursor rules, a system prompt, an MCP server’s instructions): point them at the raw files, or paste SKILL.md and the reference you need. /llms.txt lists them too.

The skill drives the falak CLI, so the agent needs a working falak and credentials. Install the CLI with curl -fsSL https://falak.sh/install-cli.sh | sh, then pick one:

You sit next to the agent. Log in yourself, once:

Terminal window
falak login --url https://falak.example.com

The browser sign-in stores a token named CLI — <host> with your role’s permissions in the CLI’s credentials file. It expires 90 days after its last use (a year after the login at most), and falak logout revokes it. Convenient, but the agent can then do everything your role allows.

The agent runs unattended, or you want to limit it (recommended). Create an API token for it in Settings → API tokens, with only the abilities it needs and an expiry, and pass it through the environment:

Terminal window
export FALAK_URL=https://falak.example.com
export FALAK_TOKEN=… # from your secret manager; never commit it or paste it into the chat
falak whoami # user, organization, role, token name and abilities

Or store it for the CLI with printf '%s\n' "$FALAK_TOKEN" | falak login --url "$FALAK_URL" --token-stdin. falak logout then forgets it but doesn’t revoke it: revoke pasted tokens in Settings → API tokens. FALAK_CONFIG_DIR keeps an agent’s credentials apart from yours.

A token belongs to one organization, and a request passes only when the token has the ability and its owner’s role has the permission, so an agent never does more than the person who created its token. Suggested sets:

The agent should Abilities
Look around (read-only) sites.view, servers.view, deployments.view, telemetry.view, projects.view, databases.view, functions.view, config.view
Deploy and roll back existing sites (CI) sites.view, deployments.view, deployments.create, deployments.rollback
Work with falak.yaml projects.view, config.view, config.apply, secrets.view, secrets.manage (+ deployments.view)
Deploy functions functions.view, functions.deploy, deployments.view, deployments.create, telemetry.view
Edit a site’s .env sites.view, sites.env.view, sites.env.manage
Deploy templates projects.view, projects.manage, templates.view, sites.create, deployments.create

Keep these for humans unless you decided otherwise: *, config.approve (approving risky changes), config.destroy (deleting data from falak.yaml), databases.manage (deleting database containers), sites.delete, servers.delete, secrets.reveal, terminal.open (consoles), network.tools and network.capture. Without them the agent asks you instead, which is what the skill tells it to do anyway. See Permissions.

  • Use the CLI with --json and branch on exit codes: 3 deployment failed, 4 a newer function version, 5 invalid falak.yaml, 6 waiting for an approval, 7 drift.
  • Never print secrets: tokens, .env contents, secret values or database passwords. Pass secrets on stdin and reference them in falak.yaml.
  • Ask before destructive or irreversible actions, and show the exact command first: deletions, --allow-destroy, approving risky runs, env push, rotating or deleting secrets, production rollbacks, consoles and packet captures, restores, and anything on the control plane host.
  • Look before changing: validate → plan → apply for config as code; falak sites show, falak plan and falak drift change nothing.

The skill documents the CLI and API of the matching Falak release, checked against the source. falak skill install --force after falak update brings it in line with your CLI.