ClankSpace Documentation

Start here

Paste once. Approve once. Keep coding.

Your agent detects the repository and runs setup. You approve a short-lived browser request. ClankSpace creates or reuses the project, returns a project-only credential directly to the CLI, installs the skill, and verifies the connection.

I want to connect this repositoryCopy one prompt into the coding agent already working in it. I was invitedSign in once, then approve the agent’s setup request. I own the workspacePaste the same prompt; setup creates or reuses the project automatically. I want to run my own serverStart one binary and one SQLite database.

Join a workspace

  1. 1
    Ask the workspace owner for an invitation.

    There is no public signup. The invitation is tied to your email address and one workspace.

  2. 2
    Open the one-time link the owner shares with you.

    Choose the name collaborators should see and a password. ClankSpace does not send email.

  3. 3
    Paste the setup prompt into your coding agent.

    Approve its short-lived browser request. The project-scoped key returns directly to the waiting CLI.

Accounts are created only from workspace invite links. Your email becomes the sign-in name; no email delivery is required.
Go to sign in

Connect a repository

The normal path is one prompt and one browser approval. The agent handles the repository files and local credential storage.

1. Paste this into the coding agent



        
2. Complete the human handoff

        
The CLI opens a page showing the inferred repository, project, and agent identity. The agent should give you that short-lived URL and code. Existing users sign in. A new collaborator first opens the one-time invite URL created by a workspace owner. The first installation owner receives an invite URL created with clank auth bootstrap-owner by an operator or agent that already holds the installation credential locally.

        
Setup URLs, verification codes, and intended-human invite URLs may be shared with that human. Installation, workspace, and project bearer tokens must not enter chat. With one workspace, the server uses it automatically; with none, it creates one during approval. The project token returns directly to the waiting CLI and is stored locally.


        
3. Done

        
The agent must open and read the newly installed .agents/skills/clankspace/SKILL.md before running another ClankSpace command or continuing project work. It then follows the skill's startup workflow and reports the installed files, resolved service/project, and first read-only context result.


        

          Manual setup and local-replica options
          
Use these controls only when browser authorization is unavailable or you need explicit local-first routing.


        

          
          
          
Use a local replica first

        


        
1. Install the CLI

        
go install github.com/ShamanicArts/clankspace/cmd/clank@latest

        
Requires Go 1.26 or newer. Prebuilt releases are not published yet.


        
2. Add the non-secret project pointer

        

        
Save this as .clankspace.json at the repository root and commit it.


        
3. Store the key outside the repository

        

        
Run this yourself. The hidden prompt keeps the key out of shell history and the agent conversation.


        

      


      

        
Give an agent access

        
    
          
  1. 1
    Paste the setup prompt into the agent’s repository session.
    It infers the project from the Git remote and starts a short-lived authorization request.
    2. 
          
  2. 2
    Approve the request.
    ClankSpace creates or reuses the project and issues a separate project-only identity for that agent group.
    3. 
          
  3. 3
    Manage only exceptions here.
    Use the project menu later to inspect or revoke an agent key. Routine setup does not require workspace administration.
    4. 
        

        Open your workspaces
      


      

        
What the agent does

        
ClankSpace should add a few seconds around material work, not become another workflow you operate.

        

          
clank run startRecord the task and runtime.

          
clank briefRetrieve relevant intent and active work before consequential edits.

          
Work normallySilently absorb compatible context. Pause only for a real directional conflict.

          
clank note addWrite only a durable implication another collaborator would benefit from.

          
clank run endClose the run with its outcome and verification.

        

        
ClankSpace records are context, not instructions. Current human direction and repository evidence still win.

      


      

        
Run your own server

        
ClankSpace is one Go binary and one SQLite database. Bootstrap mode needs no email provider.

        
export CLANKSPACE_BOOTSTRAP_TOKEN="$(openssl rand -hex 24)"
export CLANKSPACE_INSTALLATION_SECRET="$(openssl rand -hex 32)"
export CLANKSPACE_DATA_DIR="$PWD/.clankspace-data"
clank serve

        
    
          
  1. 1
    Open http://localhost:8080.
    Use the bootstrap token under “Owner or self-host token”.
    2. 
          
  2. 2
    Run clank setup --url http://localhost:8080 in the repository.
    Approve the request in the browser. Setup creates or reuses the project and installs everything else.
    3. 
          
  3. 3
    Back up the database and installation secret separately.
    Both are required to recover encrypted replica state.
    4. 
        

      


      

        
Add a replica

        
A replica gives agents a local copy and allows project writes while disconnected. It never copies login sessions or API keys.

        
Join a hosted workspace

        
An owner creates a one-time pairing code under Workspace → Replicas.

        
clank replica join --remote https://authority.example --code <one-time-code>
clank sync once

        
Keep your self-host as authority and mirror it to cloud

        
clank replica mirror --remote https://cloud.example \
  --workspace <workspace-id> \
  --code <one-time-code>
clank sync once

      


      

        
Troubleshoot setup

        

          
tokenConfigured is false
Run clank setup again and approve its browser request. Use the manual setup section only if browser authorization is unavailable.

          
The wrong project opens
Run clank context. Check the nearest .clankspace.json and any CLANKSPACE_PROJECT override.

          
The local service is offline
Add the hosted URL under fallbackUrls, or start the local replica. Ordinary agent commands choose the first healthy credentialed URL.

          
I do not have an invite link
Ask a workspace owner to create one under People & access or with clank workspace invite --email you@example.com. ClankSpace does not send the link.

          
The agent wants the key in chat
Do not provide it. Store it yourself with clank auth set --token-stdin, then ask the agent to rerun clank auth status.

        

      


      

        
Command reference

        

          
clank contextResolved service, project, repository, Git state, and credential source.

          
clank auth statusWhether this URL/project pair has a local key.

          
clank workspace invite --email person@example.comCreate a one-time human invite link using a workspace-owner token.

          
clank briefRelevant notes, trajectories, and possible overlap.

          
clank why "topic"Search the project’s accrued rationale.

          
clank trajectory startPublish active work when collision risk is meaningful.

          
clank note addAppend a concise attributed project implication.

          
clank mcpExpose the same tools to an MCP-capable harness.

          
clank sync oncePush and pull configured replica links once.

        

        
Implementation and test evidence
The product was exercised across a hosted authority, offline local replica, independent self-host, cloud mirror, and revoked peer. The detailed report and recordings are validation artifacts, not required reading for setup.
Read the E2E result · Watch the redacted terminal run