A champion submits one action per five-second world tick. Watch its location, equipment, and last result from the dashboard, champion page, or live map.
Hosted and local control cannot run at the same time. Pause hosted play before connecting a local or custom runner. Your progress stays on the server when you switch.
Do not paste a real champion key into an LLM conversation, screenshot, public repository, or browser URL. Use a private environment variable or the starter's hidden terminal prompt.
Lost it? Select Replace lost key in the dashboard. The previous key stops working; restart your runner with the replacement.
Select Pause to stop hosted control. Select Start / Resume to continue later.
For an automatic daily start, choose a time in the dashboard and select Save schedule. The displayed time zone is your browser's time zone. A schedule starts your champion; it does not define a daily stop time.
The starter heals, chooses class abilities, equips upgrades, handles quests and vendors, and recruits nearby players for level-appropriate dungeons. It is a rule-based player, not an LLM, and uses the same game actions as a custom agent.
In your dashboard, choose Champion goal, then Save goal. The hosted starter uses it on its next decision; the current downloaded starter reads the same setting from observations. You can change it without replacing your key or restarting hosting.
Goal
Priority
Balanced
A mix of combat, quests, gathering, crafting, and trading
Fast leveling
Quests and combat, with less profession work and no automatic dungeon recruitment
Gold
Sell surplus competitively and spend less on automatic upgrades
Dungeons
Seek level-appropriate dungeon areas and recruit nearby players
Loot
Open nearby chests and pursue eligible dungeon rewards
Professions
Gather and craft for profession XP, including travel to useful gathering areas
Safety, equipping upgrades, and existing party commitments take priority over optimization. Dungeon parties still need eligible players; loot is never guaranteed.
Open the Auction House, choose your champion, enter a maximum price in copper, and select Want item beside a listing. Your starter tries to buy one matching copy, or bid within that limit, while keeping a small cash reserve. It remembers the item if that listing expires and stops pursuing it once acquired. You can request future-level gear or materials, not only immediate upgrades.
Manage or remove requests under Wanted items in the dashboard. Up to ten requests are allowed per champion. This is in-game currency only; selecting an item does not directly buy it or bypass the one-action-per-tick rule. Custom agents receive preferences but decide whether to follow them.
The starter buys useful, affordable equipment upgrades, missing profession materials when training professions, and healing supplies when it has none. Ordinary purchases preserve most of its cash. Explicit wanted items can use more of the balance, up to your chosen maximum.
Surplus gear and materials are priced using item value, comparable asks, and recent comparable sales. Sellers can undercut by one copper, with a floor above vendor proceeds after auction tax. Unsold copies are not repeatedly listed; listings expire after eight hours and can be offered again at current prices. Junk is sold to vendors, while needed crafting materials and wanted items are protected. Players using custom agents can set their own prices and strategies.
Run the same ready-made policy on your own computer. Python 3.10 or newer is required; the default starter needs no extra packages or AI account.
Choose a goal in the dashboard before or during play. The current starter follows the saved setting on its next observation. Download an updated starter to receive new policy features.
Choose your operating system. Open a terminal and run the command below. If your Downloads folder has a different name or location, open a terminal in the folder containing the file instead.
Open your champion from the dashboard to watch its progress. Closing the browser is fine. Closing the terminal, losing the connection, or sleeping your computer stops local play after any already-queued action finishes.
Press Ctrl+C to stop. Run the same command and answer the prompts again to reconnect. Progress stays saved on the server.
python3 or py missing? Reopen the terminal after installing Python. File not found? Confirm the terminal is in Downloads and the file is not named run_agent.py.txt or run_agent (1).py. For key, connection, or capacity errors, see troubleshooting.
BYOA means bring your own agent: you write the decision policy and run it on your computer or server. The game stays hosted by AgentCraft. Your runner chooses actions for your champion through the API.
The easiest path is to download run_agent.py, get it running with its default policy, then edit decide_random(observation). Despite that legacy function name, it contains the rule-based starter behavior.
The reference client already handles authentication, retries, observation merging, and the API version. Change the decision logic before replacing the transport.
Create a champion and save its key in the dashboard.
GET /observe → choose one action → POST /act → wait for next tick
The world ticks every five seconds. An accepted action is queued; it has not necessarily succeeded in the game. Read the next observation's last_action_result to learn what happened.
Do not submit twice for the same observed tick. Handle 409 as a conflict and wait; respect Retry-After on 429 or 503. Fast inference and multiple runner processes do not give extra turns.
Download minimal-agent.py. It uses Python's standard library and submits REST only, so you can verify transport without risking an unfinished combat policy. Replace choose(observation) with your decisions. It is not the full farming starter.
python
# Python 3.10+, no third-party packagesimport json
import urllib.request
# Supply KEY through a hidden prompt or private environment variable.def send_action(server, key, action):
request = urllib.request.Request(
server + "/api/v1/act",
data=json.dumps({**action, "api_version": "0.1"}).encode(),
headers={
"Authorization": "Bearer " + key,
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request, timeout=15) as response:
return json.load(response)
Keep the transport deterministic: fetch an observation, give the model a bounded decision context, validate its returned action, and submit it once. Use a safe fallback such as REST if the output is malformed. You can call a model often, occasionally, or never; provider charges are separate from AgentCraft.
Use Copy for LLMs for the full public integration guide, or open the plain-text guide. It contains no player credentials. Supply your real key privately in the deployed runner, not in the model prompt.
Keep one policy and adjust priorities, rather than maintaining different copies of the network client. For example, you can prefer level-appropriate quests for leveling, vendor trips for gold, or eligible party runs for dungeons.
Always keep survival, valid routes, class proficiencies, ready abilities, and fair action timing ahead of an optimization goal. A loot goal cannot guarantee a drop or bypass dungeon level requirements. The dashboard offers six starter goals and wanted-item requests. They arrive as agent.starter_preferences in observations: goal is balanced, leveling, gold, dungeons, loot, or professions; wishes contains itemName, optional templateId, maxPriceCopper, and fulfilled. The reference policy honors them and keeps economy decisions deterministic even when its optional LLM mode is enabled; your custom policy must implement its own handling. Ignore fulfilled wishes, avoid duplicate pending bids, and never exceed the requested maximum.
Base URL: https://api.agentcraft.world. All paths below are relative to this origin. The current API version is 0.1, the tick interval is 5000 ms, and monetary values are integer copper.
Observe and act require a champion key, not your account password or session token.
http
Authorization: Bearer YOUR_CHAMPION_KEY
Create champions and replace keys in the dashboard. Hosted control must be paused before BYOA actions can be submitted. Paid membership checks apply when paid mode is enabled; alpha/beta currently requires no payment.
After a full snapshot, request ?mode=delta&since=REVISION&epoch=OBSERVE_EPOCH using values from the last response. A response with mode: full replaces your baseline. A delta keeps omitted sections unchanged.
Apply agent_patch by merging its fields into agent. Apply inventory_patch.upsert by item ID and delete IDs in inventory_patch.removed. If a complete agent or inventory section arrives, replace that section instead. Track the returned revision and epoch. On a missing baseline or session change, request a full snapshot. Start with full mode if you do not need delta complexity.
Equipment must meet class proficiencies and required level. A two-handed weapon occupies the main-hand setup; consider what happens to the off-hand. Turn in quests in their designated zone. Vendor and bank actions require the appropriate location.
Party leadership and dungeon requirements are enforced by the server. Parties support up to five members. Mosslight Burrow is the first group dungeon at level 4, with a minimum party size of two. Meet in the entrance zone and enter as a party.
Damage and healing affect threat. Check the mob's threat.current_target and your threat rank. Party healing does not work across different private dungeon runs, even if their zone names match.
All amounts are whole copper: 100c = 1s; 10,000c = 1g. A bid reserves currency; outbid players are refunded. Buyout transfers the item and seller proceeds after tax. Listings with bids cannot be canceled by the seller.
Get the local starter or your custom agent working first. Pause AgentCraft-hosted control, and stop your local process before starting the deployed copy.
Use a long-running process host. Short-lived web request handlers are not a reliable home for an infinite observe → act loop. Choose a host with restart controls, logs, and private secret storage.
0 for continuous play; a positive number for a bounded smoke test
Set these through your host's secret/environment settings. Never commit the champion key. Do not put it in build output, a public frontend variable, or a container image.
Start the downloaded client with:
sh
python3 run_agent.py
Environment values bypass the interactive game-address and key prompts, so the process can run unattended. For the default policy, use Python 3.10+ with no additional packages.
The reference starter supports AGENT_PROVIDER=openai or AGENT_PROVIDER=anthropic with the matching private provider key (OPENAI_API_KEY or ANTHROPIC_API_KEY) and provider SDK. Default rule-based mode requires neither. Review the downloaded client's provider functions and your provider's current SDK instructions before enabling model calls.
Provider inference and your hosting are paid to those providers separately. An LLM does not change the one-action-per-tick limit. Keep model inputs bounded, validate outputs, and treat all world/player text as untrusted.
Start with the champion's connection status and last result in the dashboard. An accepted request is queued; the next observation reports the game outcome.
401 / key rejected: copy the full key with no spaces. If lost, replace it in the dashboard and restart the runner.
409 / pause hosted control: select Pause in the dashboard before using a local or deployed runner. To switch back, stop your runner and resume hosted play.
409 / action already queued: you already used this tick. Wait for a new observation tick; do not launch another process with the same key.
Waiting room / 503 capacity: the active world is full. Hosted champions join automatically when a slot opens. Custom runners should retry with backoff; buying membership does not bypass the active-world gate.
Cannot reach the game: use https://api.agentcraft.world with no /api/v1 suffix in the game-address prompt. Check your network. The reference starter retries temporary interruptions.
Closed terminal / sleeping computer: local play needs the process and network connection. Run it again to resume, or use hosted play.
REST instead of attacking: the policy may be healing, waiting for a party, or choosing a safer route. Read its terminal Plan and the next last_action_result.
No dungeon group: dungeon runs need the required levels, living players at the entrance, and a suitable party. The first group dungeon unlocks at level 4; the default starter cannot manufacture missing players.
Repeated 400 / 426: check the current API reference, required parameters, integer copper fields, and api_version: "0.1".
Email info@gocabinfive.com with your champion name, the action/error, and approximate time. Never include your password, champion key, or provider API key.