User Guide

Managing Assistants

Creating an Assistant

1. Click “Create Assistant” in the top-right of the My Assistants tab

2. Fill in:

   • Name — unique per user, lowercase, hyphens allowed (e.g. my-project)

   • Description (optional) — free-form text

   • Provider — select DKubeX; enter your API key; choose a model from the dropdown (the dropdown validates the key live)

   • Workspace source (optional) — blank project or git clone (see below)

3. Click “Create”

The assistant card immediately shows starting; status updates in real time via Server-Sent Events and transitions to running once the pod’s readiness probe passes.

Workspace Sources

Set the workspace source when creating an assistant to control what lives in /home/<user>/<dir>/:

Blank project:

{
  "workspace_sources": [
    { "type": "blank", "dir": "my-project", "git_init": true }
  ]
}

• git_init: true runs git init in the directory after creation.

Clone from git (SSH):

{
  "workspace_sources": [
    { "type": "git", "dir": "my-project", "url": "git@github.com:org/repo.git", "ref": "main" }
  ]
}

• Requires a DKubeX SSH key configured in your account settings.

• ref defaults to main if omitted.

Assistant Configuration

The configuration JSON object accepts:

Field	Type	Default	Description
model_provider	string	—	Provider ID (e.g. securellm)
model	string	—	Model ID selected from the provider’s list
model_api_key	string	—	API key (stored as a Kubernetes Secret; never returned in API responses)
model_base_url	string	provider default	Override the provider’s base URL
workspace_sources	array	[]	Workspace initialization entries
resources.cpu_request	string	100m	Pod CPU request
resources.cpu_limit	string	2000m	Pod CPU limit
resources.memory_request	string	256Mi	Pod memory request
resources.memory_limit	string	1Gi	Pod memory limit

Assistant Lifecycle

Action	From status	Result
Start	stopped	Creates Kubernetes resources; status → starting → running
Stop	running	Deletes Kubernetes resources; status → stopping → stopped
Restart	running	Deletes then recreates resources; status → starting → running
Delete	any	Deletes all Kubernetes resources and the database record

The workspace PVC is not deleted when an assistant is stopped — data persists. The PVC is removed only when the assistant is deleted.

Coding-Agent Terminals

Once an assistant is running, click its card to open it. The toolbar shows links for each agent TUI:

Tab	Path	Description
OpenClaw	/agentx/<uuid>/webui/	AI gateway web interface
Terminal	/agentx/<uuid>/shell/	Plain bash shell
Claude Code	/agentx/<uuid>/claude/	Anthropic Claude Code CLI
OpenCode	/agentx/<uuid>/opencode/	anomalyco/opencode CLI
Gemini CLI	/agentx/<uuid>/gemini/	Google Gemini CLI
Codex CLI	/agentx/<uuid>/codex/	OpenAI Codex CLI
Copilot CLI	/agentx/<uuid>/copilot/	GitHub Copilot CLI
Mistral Vibe	/agentx/<uuid>/vibe/	Mistral Vibe coding agent

Each terminal is lazily activated — the process starts on your first click. If you close the browser tab, the session keeps running and reconnects when you return.

Viewing Logs

1. Open an assistant card

2. Click “View Logs”

3. Live log lines stream from the pod via SSE

4. Stream automatically closes after 5 minutes of inactivity or when you close the panel

Pinning Assistants

Click the pin icon on any assistant card (owned or shared) to add it to your pinned section at the top of the list. Pins persist across sessions and are personal to your account.

---

Sharing Assistants

Share with Users

1. Open an assistant card → click “Share”

2. Search by username or email

3. Select the permission level:

Permission	What the recipient can do
VIEW	See assistant details and metadata
USE	Open terminals, view logs, interact with the assistant
MANAGE	Edit configuration, restart, start/stop, modify settings

4. Click “Share”

The recipient sees the assistant immediately in their “Shared with Me” tab.

Managing Shares

• Update permission: open the Shares panel on an assistant → click “Edit” next to a share → change level → Save

• Revoke: click “Remove” next to a share → confirm

Accessing Shared Assistants

Navigate to the “Shared with Me” tab to see all assistants shared with you. The permission level is shown on each card and determines which actions are available.

Shared assistant limitations:

• Only the owner can delete, share with others, or publish as a template

• The owner retains full control regardless of what permission was granted to others

---

Templates

Templates are saved assistant configurations that can be shared and redeployed.

Publishing a Template

1. Open a working assistant → click “Publish as Template”

2. Provide:

   • Name — template name (unique)

   • Description

   • Tags — comma-separated, for filtering (e.g. python,claude)

   • Version — semantic version (e.g. 1.0.0)

   • Metadata (optional) — JSON object with arbitrary extra info

3. Click “Publish”

Deploying from a Template

1. Browse the Templates tab

2. Click “Deploy” on a template

3. Provide a unique assistant name

4. Click “Create”

Template Versions

• Each published template can have multiple versions

• Versions can be marked as deprecated with a message

• When deploying, the latest non-deprecated version is used by default

---

Admin Features

The “Admin” tab is visible only to users with the admin role.

System Health

Displays:

• Total users, total assistants, running/stopped/error counts

• Database health status

• Kubernetes status (enabled / disabled)

• API uptime

User Management

Action	Steps
List users	Admin → Users tab
View user	Click a user row
View user’s assistants	Admin → GET /api/v1/admin/users/{id}/assistants
Update role	Click user → Edit → change role → Save
Delete user	Click user → Delete → confirm

Role changes are written to the audit log.

Assistant Management

Admins can see, stop, and delete any assistant regardless of owner:

• List: Admin → Assistants tab; filter by status, owner, or search by name

• Stop: click Stop on any running assistant; action is logged

• Delete: click Delete; action is logged

Pod Metrics

Admin → Metrics shows CPU (millicores) and memory (MiB) for every pod labeled app=agentx, mapped to their assistant name.

Audit Logs

Admin → Audit Logs shows all recorded admin actions (newest first). Filter by action type or search by resource ID / username.

Current logged actions:

• admin.assistant.stop

• admin.assistant.delete

---

Best Practices

Naming

• Use lowercase with hyphens: code-reviewer, data-pipeline

• Be project-specific: my-project-dev, my-project-prod

Resource Management

• Stop assistants when not actively used — the workspace PVC is preserved

• Monitor resource usage via the Admin metrics panel

• Set appropriate CPU/memory limits to avoid cluster resource starvation

Security

• Never put raw secrets in the configuration JSON beyond model_api_key (which is stored as a Kubernetes Secret and filtered from API responses)

• Use the SSH key feature for git workspace sources rather than embedding credentials

Sharing Strategy

• Grant VIEW to reviewers who just need to see the setup

• Grant USE to teammates who will interact with the assistant

• Grant MANAGE only when the recipient needs to modify configuration

---

Troubleshooting

Assistant stuck in starting

• Check the pod’s events: kubectl describe pod <name> -n <namespace>

• Check logs: kubectl logs <pod> -n <namespace>

• Common causes: invalid API key (validated pre-flight but may fail at runtime), SSH key missing for git source, insufficient cluster resources

Cannot share with a user

• Verify the username/email exists in AgentX (users are provisioned on first login)

• Check if already shared (re-sharing the same user raises a conflict)

Agent terminal shows blank or error

• The agent process lazy-starts; wait a few seconds on first open

• If status is error, the pod has crashed — check pod logs and events (kubectl describe pod) for the specific failure

Logs not streaming

• Confirm the assistant status is running

• Refresh the page

• Streams close after 5 minutes of inactivity; reopen via the Logs button

Template deployment fails

• Check that the template’s model_api_key is still valid (keys are stored in the template configuration)

• Ensure the workspace source (if any) is still accessible

• Check for naming conflicts with existing assistants