Testing Locally

Before publishing an agent, you’ll want to test it thoroughly. Selu runs entirely in Docker, so your local testing workflow revolves around the web chat, container logs, and direct capability invocation.

Installing your agent

Place your agent directory (containing agent.yaml and agent.md) inside the installed_agents folder that is volume-mounted into the Selu container. If you followed the default Docker setup, this is the installed_agents directory next to your docker-compose.yml:

installed_agents/
  my-agent/
    agent.yaml
    agent.md

After adding or modifying an agent, restart Selu so it picks up the changes:

docker compose restart

Selu scans the installed_agents directory on startup and loads every valid agent it finds.

Testing in the web chat

Open http://localhost:3000 in your browser. Select your agent from the agent list, then send messages to test its behaviour. This is the fastest way to iterate on your system prompt and verify end-to-end behaviour.

Tip

After editing agent.md or agent.yaml, run docker compose restart to reload the agent. Keep the browser tab open — you can start a new conversation immediately after the restart completes.

Viewing logs

All Selu logs are available through Docker Compose:

docker compose logs selu           # Selu orchestrator logs
docker compose logs selu -f        # follow (stream) logs in real time
docker compose logs selu --tail 50 # last 50 lines

The orchestrator logs include agent loading, LLM calls, capability invocations, and errors. This is the first place to look when something isn’t working.

Debugging capabilities

If a capability isn’t behaving as expected, there are several approaches.

Check capability container logs

Each capability runs in its own container. List running containers and inspect their logs:

docker compose ps                          # list all containers
docker compose logs <capability-service>   # logs for a specific capability

Capability containers write to stdout/stderr, which Docker captures.

Manual gRPC call

Use grpcurl to invoke a capability directly, bypassing the orchestrator. This is useful for isolating whether a problem is in the capability itself or in the agent’s routing:

grpcurl -plaintext \
  -d '{"tool_name": "weather_lookup", "parameters": "eyJsb2NhdGlvbiI6ICJCZXJsaW4ifQ=="}' \
  localhost:50051 selu.capability.Capability/Invoke

Note

The parameters field is a bytes type in the gRPC schema, so you need to pass a base64-encoded JSON string. The example above encodes {"location": "Berlin"}. You can generate the base64 value with: echo -n '{"location": "Berlin"}' | base64

Shell into the container

For deeper debugging, open a shell inside the capability container:

docker exec -it <container-name> /bin/sh

From there you can inspect files, check environment variables, test network connectivity, or run the capability’s code manually.

Environment variables and credentials

Capabilities that need API keys or configuration can read from environment variables. You can set these in your docker-compose.yml or in a .env file that Docker Compose loads automatically.

.env

WEATHER_API_KEY=your-api-key-here

Note

For production use, API keys and other credentials are managed through the Selu dashboard rather than .env files. The .env approach is convenient for local development, but the dashboard provides a more secure way to manage secrets in deployed environments.

Next steps

Once your agent works locally, review the Marketplace Guidelines to prepare for publication.