`AGENT_SERVER_URL` is documented but never applies, because `config.yaml` always sets `server.url`

[rodriguecyber]

Difficulty: Beginner · You'll need: Go, or just careful reading · Size: ~10 lines

What's going on

apps/agent/.env.example advertises an environment override:

AGENT_SERVER_URL=ws://localhost:3000/agents

apps/agent/internal/config/config.go reads it — but only as a fallback when the YAML left server.url empty:

if c.Server.URL == "" {
    c.Server.URL = os.Getenv("AGENT_SERVER_URL")
}
if c.Server.URL == "" {
    return fmt.Errorf("server.url is required when AGENT_SERVER_URL is not set")
}

And apps/agent/config.yaml always sets one:

server:
  url: ws://127.0.0.1:3000/agents

So with the shipped config, AGENT_SERVER_URL never takes effect. Setting it does nothing, silently.

Why it matters

Silent no-ops are worse than missing features. Someone pointing an agent at a different platform will reasonably reach for the documented environment variable, restart the agent, and watch it connect to the old URL with no warning anywhere in the logs.

Environment overrides also matter more than usual here: the agent runs as a systemd unit, where dropping an Environment= line into the unit file is often easier than editing a YAML file the installer owns.

Two honest options

A. Make the env var win. Standard precedence is flags > environment > config file > defaults. Check AGENT_SERVER_URL before falling back to the YAML value rather than after. Roughly a two-line reorder — but it changes behaviour for anyone who has the variable set for other reasons, so it belongs in the PR description.

B. Make it honest. If YAML is meant to be authoritative, remove the variable from .env.example and adjust the error message, which currently implies the variable is a supported way to configure the URL.

A is probably right — the variable exists, it is documented, and env-over-file is what people expect. But B is a legitimate call if the project wants one configuration source.

While you are in there

AGENT_CONFIG is also listed in .env.example, but cmd/agent/main.go only reads the -config flag — os.Getenv("AGENT_CONFIG") appears nowhere. Same class of problem. Worth confirming and handling in the same PR.

How to verify

cd apps/agent
go build ./... && go test ./...

AGENT_SERVER_URL=ws://example.test:9999/agents ./docksight-agent
# the startup log line "configuration loaded" prints the resolved server URL

Under option A that log must show example.test. Also confirm that without the variable set, the YAML value is still used.

Done when

• AGENT_SERVER_URL either works or is no longer documented
• The same is settled for AGENT_CONFIG
• The error message in validate() matches the actual behaviour
• docs/agent.md agrees with whatever was chosen

---

Good first contribution. Mostly reading rather than writing — tracing a documented feature through the code to find it never fires. That trace, written into the PR, is the valuable part.

[aryansinha1908]

I would like to work on this issue, please.

[rodriguecyber]

I would like to work on this issue, please.

please go ahead

[aryansinha1908]

I am planning to go with Option B (removing the environment variables to make config.yaml the single source of truth) as it keeps the configuration straightforward and avoids confusion. Let me know if you'd prefer Option A instead, otherwise I'll get a PR open shortly