pikasTech-unidesk/docs/reference/agentrun.md

AgentRun Development And Operations

This document records only UniDesk-side development and operations rules for the separate pikasTech/agentrun repository. AgentRun architecture, MVP scope, API design and runtime internals must live in the AgentRun repository itself, not in UniDesk reference docs.

Repository And Workspace

The canonical AgentRun repository is git@github.com:pikasTech/agentrun.git.

The fixed G14 workspace is:

G14:/root/agentrun

It must stay on branch master, use origin git@github.com:pikasTech/agentrun.git, and remain clean except for explicitly identified parallel local changes. Before any AgentRun development, deployment, documentation edit, resumed work or context recovery, run:

tran G14:/root/agentrun script -- 'pwd; git status --short --branch; git remote -v'

Expected state:

• path is /root/agentrun;
• branch is master...origin/master after the first remote push;
• origin is git@github.com:pikasTech/agentrun.git;
• fixed workspace is clean.

If the workspace is missing, dirty, on the wrong branch, or pointed at the wrong remote, repair that first. Do not use /root/unidesk, /root/hwlab, D601 workspaces, temporary clones, runner checkouts, pod-local copies or master-server copies as AgentRun source truth.

Worktree Rule

The fixed workspace is only for precheck, fetch, worktree management and final synchronization. Normal AgentRun feature/docs/deploy work should use an independent worktree:

G14:/root/agentrun/.worktree/{pr_branch}

Create worktrees from latest origin/master, keep task branches scoped to the current change, and commit only task-related files. Do not use /root/agentrun itself as a parallel scratch directory.

Deployment Targets

Default AgentRun deployment targets are G14 native k3s namespaces:

G14:k3s namespace agentrun_dev
G14:k3s namespace agentrun_prod

Use UniDesk route syntax for all k3s operations:

tran G14:k3s kubectl get pods -n agentrun_dev
tran G14:k3s kubectl get pods -n agentrun_prod

Do not use ad hoc NodePort, host port, direct pod IP, provider-gateway business HTTP proxy, or one-off port-forward as a durable AgentRun deployment path. Any public, UniDesk, HWLAB or cross-service integration path must be introduced through reviewed AgentRun repository changes and then reflected in UniDesk deployment/config docs only as an operations entry.

UniDesk Boundary

UniDesk is the distributed development and operations center for AgentRun. UniDesk may document:

• canonical repository, workspace and worktree rules;
• G14 precheck and route syntax;
• default DEV/PROD namespaces;
• deployment observation and controlled rollout entrypoints;
• how UniDesk and HWLAB should reach AgentRun once the AgentRun repo defines the public contract.

UniDesk must not be the source of truth for:

• AgentRun service architecture;
• MVP phase plan;
• RESTful API contract;
• runner/backend protocol;
• database schema;
• tenant policy model;
• backend adapter design.

Those topics belong in the AgentRun repository under its own AGENTS.md and docs/reference/.