Tutorial: Your First Pod
Beginner — 5 minutes
Learn how to create and interact with your first AgentPod step by step. By the end of this tutorial, you will have launched an AI coding agent, connected it to a repository, and completed a task.
Prerequisites
Before starting, make sure you have:
- An AgentsMesh account (sign up at the registration page)
- A Runner installed and connected (see Quick Start → Step 2)
- At least one AI agent CLI installed on your Runner (e.g., Claude Code)
- A Git repository connected (optional but recommended)
Open the Workspace
Click Workspace in the left sidebar. This is where all your Pods live. You will see an empty workspace if this is your first time.
Create a New Pod
Click the New Pod button in the top-right corner. The Pod creation dialog will open with several configuration options.
Fill in the following fields:
- Agent — Select the AI agent you want to use (e.g., Claude Code)
- Runner — Choose which Runner will host this Pod
- Repository — Select a repository for the agent to work on (optional)
- Branch — Choose the branch to check out (defaults to the main branch)
- Initial Prompt — Write a task description for the agent, e.g., "Add input validation to the login form"
Watch the Pod Initialize
After clicking Create, the Pod enters the Initializing state. The Runner will:
- Create an isolated Git worktree (if a repository was linked)
- Start a PTY terminal session
- Launch the AI agent with your initial prompt
Interact with Your Agent
Once the Pod is Running, you can interact with the AI agent through the web terminal:
- Type follow-up instructions directly in the terminal input
- Watch the Agent Status indicator — it shows Idle, Executing, or Waiting
- The agent works inside the isolated Git worktree, so your main branch is never affected
- Use the fullscreen button for a distraction-free view
Review and Finish
When the agent has completed your task:
- Review the changes the agent made in the terminal output
- The agent may have created commits on a worktree branch — check the git log
- Click Terminate in the Pod toolbar to stop the Pod and clean up the worktree
- The Pod status changes to Terminated and resources are freed
Troubleshooting
No Runners in the dropdown
Your Runner may be offline. Go to Settings → Runners and check the status. If it shows Offline, restart the Runner process and ensure it can reach the AgentsMesh server.
Pod stuck in Initializing
This usually means the repository is large and still cloning. Wait a few minutes. If it doesn't resolve, check the Runner logs for clone errors. Try creating a Pod without a repository to test basic functionality.
Agent not responding
Verify the AI agent CLI is installed on the Runner (e.g., run 'claude --version' on the Runner machine). Check that the API key environment variable is set correctly. The agent may also be waiting for permission — look for a permission prompt in the terminal.
Pod immediately terminates
This often means the agent CLI crashed at startup. Check that your API key is valid and not expired. Try running the agent CLI manually on the Runner to see the error message.
What Should I Do Next?
Congrats! You have a working Pod. Your next step depends on what you want to achieve: