# Vikunja access — agent onboarding prompt Hand the block below to any agent that needs Vikunja access. It is written to be pasted verbatim as a task prompt. Everything after the `---` is the prompt. Before pasting, substitute: - `` — the bot account for this harness, e.g. `bot-nullclaw` - `` — `claude-code`, `omp`, `picocode`, or `other` --- ## Task: configure your own Vikunja access You are ``. Give yourself working access to Vikunja at `https://todo.dominat.us`, then verify it and report what you can and cannot see. ### Facts you need - Tooling lives at `/srv/pods/vikunja-agents/` on `reptar`: `vk` (CLI), `vkclient.py` (shared client), `vikunja_mcp.py` (MCP server, stdio). Standard-library Python only — no virtualenv, no pip install. - If you are **not** on `reptar`, copy those three files to the machine you run on (`~/opt/vikunja-agents/`) and symlink `vk` onto your `PATH`. - Auth is a Vikunja **API token**, read from `~/.config/vikunja-agents/config.json` (mode 0600) or `$VIKUNJA_TOKEN`. Select an identity with `$VIKUNJA_PROFILE`. - Your account must already exist. The normal shape is a **bot user**: a local account owned by a human, with no password of its own. If it does not exist, stop and ask — creating one is your owner's job (Vikunja UI: Settings → Bot Users). MAS/OIDC accounts cannot be used for this (see constraints). ### Step 1 — get your token (once) **If your account is a bot user** (the normal case — it has an owner and no password), you cannot mint your own token: token creation needs a password login and bots have none. Your owner mints it for you, then hands it over out of band. Store it without putting it in argv or shell history: ```sh vk profile --username < /path/to/token-file # or: pbpaste | vk profile --username ``` `vk profile` verifies the token against the API before saving, so a bad paste fails loudly instead of silently writing a dead profile. It lands in `~/.config/vikunja-agents/config.json` at mode 0600. If you have no token, stop and ask your owner for one. They create it from Vikunja's UI (Settings → API tokens, issued for your bot) or with an authenticated `PUT /api/v1/tokens` carrying `owner_id: `. **If your account is instead a plain user with a password** (legacy), you can mint your own: ```sh VIKUNJA_PASSWORD="$(cat ~/.config/vikunja-agents/.password)" \ vk bootstrap --username --title " ($(hostname))" ``` Either way: **never echo the token, paste it into a chat, or commit it.** It expires in a year and cannot renew itself — renewal means asking your owner again. ### Step 2 — register the MCP server for your harness `claude-code`: ```sh claude mcp add vikunja -e VIKUNJA_PROFILE= -- /srv/pods/vikunja-agents/vikunja_mcp.py ``` `omp` — add to `~/.omp/agent/mcp.json` (create it if absent): ```json { "mcpServers": { "vikunja": { "type": "stdio", "command": "/srv/pods/vikunja-agents/vikunja_mcp.py", "env": { "VIKUNJA_PROFILE": "" } } } } ``` `picocode` — add to `picocode.yaml`: ```yaml mcp: vikunja: command: /srv/pods/vikunja-agents/vikunja_mcp.py env: VIKUNJA_PROFILE: auto_allow: - "^vikunja_list_" - "^vikunja_get_" ``` `other` — the server speaks MCP over stdio (JSON-RPC 2.0, newline-delimited). Run `/srv/pods/vikunja-agents/vikunja_mcp.py` with `VIKUNJA_PROFILE` set. If your harness cannot speak MCP, skip this step and use the `vk` CLI instead; it covers the same ground. ### Step 3 — verify, and do not skip this ```sh vk whoami # must print vk projects # the projects you can actually see vk tasks --mine # your queue ``` Then confirm the MCP path independently of the CLI — restart your harness if it binds MCP servers at startup (claude-code does), and call `vikunja_list_projects`. If the tool is missing, the registration did not take; if it errors, the token did not take. These are different failures — do not report one as the other. ### Step 4 — report State plainly: 1. Which projects you can see (likely only your own `Inbox` — see constraints). 2. Whether MCP tools are available, or whether you fell back to the CLI. 3. Anything you had to ask a human for. ### Constraints that will otherwise cost you an hour - **A token cannot mint another token.** Vikunja excludes the `tokens` route group from anything an API token can be granted. For a bot user that means only your owner can issue or renew your token; you can never do it yourself, and there is no password you could use even if you wanted to. - **You cannot ask the API who you are.** `/user` is unreachable with a token (`user_*` routes are excluded too). `vk whoami` reads the username from your config file. Do not try to fix a 401 on `/user` — it is expected. - **You start with only your own Inbox.** A new account sees nothing else until a human shares projects with it. If `vk projects` shows one project, that is normal, not a broken token — say so and ask for the shares you need. - **Assignment is dispatch.** Work reaches you by being assigned to ``. Use `vk tasks --mine`. Do not scrape other agents' queues. - **Username lookup is project-scoped.** Resolving a username to an id uses `/projects/{id}/projectusers`; the instance-wide `/users` search is not grantable to tokens. You can only assign to users who can access that project. - **Updates replace the whole task.** The client merges for you; if you call the API directly, read-modify-write or you will blank fields. - **Link your work back.** Put `VK-` in commit messages, and `fixes VK-` to close a task on push — a Gitea bridge posts the commit link onto the task. Without it a task says "done" but never says what changed. ### Rules - One account per harness. Do not share a profile with another agent — separate accounts are what make the task history say who did what. - Never print, log, or transmit the token or password. If you think one leaked, say so immediately; rotation needs a human. - Comment on tasks when you finish work, find something that changes scope, or are blocked. Do not narrate routine steps.