Deploy Your Own Image

Any container image can run on AgntSpark if it serves HTTP on its port. To work with the console, health checks and the rest of the platform, serve the runtime contract: GET /health and POST /invoke.

Requirements

• Public image. The image must be pullable without credentials, e.g. from Docker Hub or a public GitHub Container Registry package. Building from source (build_path) isn't supported yet.
• Listen on deploy.port (default 8080) on all interfaces (0.0.0.0).
• Stateless between replicas. Requests to an agent with several replicas go to a random replica, so keep state such as conversation history somewhere shared, or run one replica.
• Don't run as root if you can avoid it. Containers run without Linux capabilities beyond the basics, can't gain privileges, and are limited to 512 processes.

Your container can reach the internet but not other agents, the platform's database or the cloud metadata service.

Option 1: Build on the runtime image

The quickest route to your own tools and prompt is the platform's runtime, agntspark-core, which already serves the contract. Write an agent.yaml and a tools.py:

# agent.yaml
name: calculator
system_prompt: You add numbers. Use the add tool.
llm: {provider: anthropic, model: claude-sonnet-4-5, temperature: 0.2}
tools:
  - name: add
    description: Add two integers.
    handler: tools:add
    parameters: {a: first number, b: second number}

# tools.py
def add(a: int, b: int) -> str:
    return str(int(a) + int(b))

FROM python:3.12-slim
RUN pip install "agntspark-core[llm,server] @ git+https://github.com/AgntSpark1/agntspark-core.git"
COPY . /template
ENV AGNTSPARK_TEMPLATE_DIR=/template
EXPOSE 8080
CMD ["python", "-m", "agntspark_core", "serve", "--port", "8080"]

Test it locally before pushing:

docker build -t ghcr.io/you/calculator:1 .
docker run --rm -p 8080:8080 -e ANTHROPIC_API_KEY=… ghcr.io/you/calculator:1
curl -s localhost:8080/invoke -H 'content-type: application/json' -d '{"input": "2 + 3?"}'

Option 2: Any framework

Serve the two endpoints yourself. A minimal FastAPI example:

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok", "contract": "v1"}

@app.post("/invoke")
def invoke(body: dict):
    answer = run_my_agent(body["input"], body.get("session_id"))
    return {"output": answer, "session_id": body.get("session_id") or "new"}

Deploy it

curl -X POST https://agntapi.agntspark.com/v1/agents \
  -H "Authorization: Bearer $AGNTSPARK_API_KEY" -H 'content-type: application/json' \
  -d '{
    "name": "calculator",
    "model": "claude-sonnet-4-5",
    "api_key": "'"$ANTHROPIC_API_KEY"'",
    "deploy": {
      "image": "ghcr.io/you/calculator:1",
      "port": 8080,
      "resources": {"cpu": 0.5, "memory_mb": 512}
    }
  }'

Environment your container receives

Variable	Value
AGENT_ID	The agent's id, agt_…
AGENT_NAME	The agent's name
SYSTEM_PROMPT	The prompt you set, or empty
LLM_MODEL	The agent's model
LLM_PROVIDER	openai, anthropic or google, from the model name
OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY	The api_key you passed, under the provider's name
Your deploy.env entries	As given; secret: true values are stored encrypted and shown masked

Ship a new version

Push a new tag and redeploy with it:

curl -X POST https://agntapi.agntspark.com/v1/agents/agt_…/deploy \
  -H "Authorization: Bearer $AGNTSPARK_API_KEY" -H 'content-type: application/json' \
  -d '{"image": "ghcr.io/you/calculator:2", "port": 8080}'

A redeploy replaces the running containers, so expect a short interruption. Your model key is kept.

Troubleshooting

Symptom	Check
URL returns plain-text 401	The agent is private: send Authorization: Bearer agk_….
Status failed	The agent's error field: usually the image couldn't be pulled.
URL returns 503 This agent is not running.	No replica is up. Look at the logs, then redeploy.
URL returns 502	Your process isn't listening on deploy.port, or crashed.
/health returns 503 unconfigured	The model key is missing or for the wrong provider.