Best Practices and Troubleshooting

Agents work best with Okteto when they follow the same patterns human developers use: deploy through the CLI, build with the Okteto Build Service, read okteto.yaml for service discovery. Most issues come from agents bypassing these patterns.

Command rules

This is the full list of which commands agents may run. The collaborative and autonomous workflow pages link here.

Command	Agent may run?	Notes
okteto deploy --wait	Yes	Builds images and deploys all services. Always pass --wait.
okteto build <service>	Yes	Builds a single image through the Okteto Build Service.
okteto test <name>	Yes	Runs a test container defined in okteto.yaml.
okteto validate	Yes	Checks okteto.yaml for syntax and schema errors.
okteto logs <service>	Yes	Views container logs.
okteto endpoints	Yes	Lists public URLs for the environment.
okteto doctor	Yes	Generates a diagnostic bundle for troubleshooting.
okteto exec -- <command>	Collaborative only	Runs a command in the active Development Container.
okteto status	Collaborative only	Checks file sync progress during a dev session.
okteto down	Yes	Exits dev mode for a service. Restores the deployment without destroying the environment.
okteto up <service>	Never	Interactive, hangs if an agent runs it. The human runs it in collaborative mode.
okteto namespace create <ns>	Yes	Creates an isolated Namespace for a worktree. See Worktree isolation.
okteto namespace delete <ns>	Only one it created	Deletes a Namespace. Safe only for one the agent created for a worktree, never a shared or pre-existing Namespace.
okteto destroy	Only with authorization	Tears down all resources. Needs explicit policy or human approval. See Cleanup and teardown.
kubectl / helm directly	No	Bypasses Okteto's resource tracking. Use okteto deploy instead.

Every command that targets an environment accepts a -n <ns> flag to run against a specific Namespace without changing the active context. Agents use it to isolate git worktrees. See Worktree isolation.

The sections below explain the reasoning behind the rules that matter most.

Best practices

Read okteto.yaml for service discovery

Agents should read the okteto.yaml manifest to discover services, build targets, and test definitions. Don't hardcode service names or assume a fixed project structure.

# Good: agent reads okteto.yaml to find services
# The plugin teaches agents to do this automatically

# Bad: agent hardcodes "api", "frontend", "worker"
okteto build api  # What if the service is called "backend"?

Reading the manifest makes the agent portable across projects.

Use okteto build, not local Docker builds

Agents should use okteto build to build container images. This uses the Okteto Build Service, which pushes images directly to the Okteto Registry where they're accessible to the environment.

# Good
okteto build api

# Bad — image won't be in the registry
docker build -t api .

Use okteto deploy, not raw kubectl or helm

okteto deploy handles building images, deploying services, and cleaning up resources when the environment is torn down. If an agent uses kubectl or helm directly, those resources won't show up in the Dashboard, won't get cleaned up automatically, and can leak across environments.

# Good — builds, deploys, and tracks everything
okteto deploy --wait

# Bad — resources get orphaned when the environment is destroyed
helm install my-release ./charts
kubectl apply -f manifests/

Never run okteto up from an agent

okteto up starts an interactive development session with a terminal and file sync. It requires human interaction and will hang if an agent runs it.

• In collaborative mode: the human runs okteto up, the agent uses okteto exec
• In autonomous mode: use okteto deploy + okteto build instead

Never run okteto destroy without authorization

okteto destroy tears down all resources in the environment. An agent should never run this without explicit policy or human approval, since it could destroy shared resources or in-progress work.

Use --wait with okteto deploy

Always pass --wait when deploying so the agent waits for services to be ready before moving on. Without it, the agent might try to test services that haven't finished starting.

# Good — waits for all pods to be ready
okteto deploy --wait

# Risky — services might not be ready yet
okteto deploy

Worktree isolation

A Namespace is the unit of isolation for everything okteto deploy creates. The active Namespace comes from the Okteto context, which is global to the machine, not per-directory. That matters the moment an agent works in more than one checkout at once.

A single primary checkout can use its context's default Namespace with no extra flags. Reach for a dedicated Namespace when parallel checkouts or git worktrees would otherwise collide. Two worktrees deploying into the same Namespace overwrite each other's environments, return the wrong data from okteto endpoints and okteto logs, and an okteto destroy in one tears down the other.

Give each worktree its own Namespace. The agent creates it once:

okteto namespace create <ns>

Then it passes -n <ns> on every command for the rest of the session:

okteto deploy --wait -n <ns>
okteto build <service> -n <ns>
okteto endpoints -n <ns>
okteto test <name> -n <ns>

Agents derive the Namespace name from the branch or worktree directory. Okteto Namespace names are lowercase alphanumeric plus -, and start and end with an alphanumeric character.

Agents use the per-command -n <ns> flag, not okteto namespace use <ns>. The use command switches the active Namespace in the shared global context, which races with any other worktree or agent on the same machine. The -n flag is per-invocation and never mutates shared state, so it's safe under concurrency.

Cleanup and teardown

Tearing an environment down matters as much as standing one up. Pick the right command, and get the authorization right.

Command	What it does	When to use
okteto down	Exits dev mode for one service and restores the original deployment. Does not destroy the environment.	The developer has finished iterating on a service but wants the environment running.
okteto destroy	Tears down every resource okteto deploy created in the Namespace. Destructive.	The environment is no longer needed and teardown is authorized.
okteto namespace delete <name>	Deletes an entire Namespace and everything in it. Very destructive.	Only for a Namespace the agent created for an isolated worktree, or with explicit user instruction.

Reaching for okteto destroy when the developer only wanted to exit dev mode is a common mistake. When in doubt, okteto down is the safe choice.

In collaborative mode, the agent surfaces okteto destroy as a suggestion and lets the developer run it. In autonomous mode, the agent runs okteto destroy only when the task authorizes cleanup, a cleanup policy is documented in the repo's CLAUDE.md or the ticket, or the environment is ephemeral and owned by the pipeline. Otherwise it leaves the environment running and reports the command the caller would use to tear it down.

A Namespace the agent created itself for an isolated worktree is the one case where it may run okteto namespace delete without a separate instruction, since it owns that Namespace's teardown:

okteto destroy -n <ns>           # remove the deployed resources
okteto namespace delete <ns>     # then remove the now-empty Namespace

Troubleshooting

Agent hangs and becomes unresponsive

The most common cause is the agent running okteto up, which is interactive and sits waiting for terminal input. Stop the agent. In collaborative mode, you keep an okteto up session running in your own terminal and the agent works against it with okteto exec. In autonomous mode, the agent uses okteto deploy + okteto build instead. The Okteto plugin for Claude Code teaches agents to avoid this automatically.

Build fails

Check the build logs from okteto build <service>. Common causes include missing dependencies in the Dockerfile, a build context that doesn't include required files, or registry authentication issues.

If the agent is trying to use docker build locally, switch to okteto build to use the Okteto Build Service.

Tests fail after deployment

First, make sure you're using okteto deploy --wait so all pods are running before tests execute. Then check okteto logs <service> --since 5m for startup errors or crash loops. Also review the test section of okteto.yaml to make sure the test container has the right image, commands, and dependencies.

Agent uses wrong service names

The agent is probably not reading okteto.yaml. Make sure the Okteto plugin for Claude Code is installed, which teaches the agent to auto-discover services from the manifest.

Environment endpoints not accessible

Run okteto endpoints to get the current URLs. If nothing shows up, check that services are deployed with okteto logs <service>, verify that your okteto.yaml or Helm chart exposes the correct ports, and confirm that okteto deploy --wait completed successfully.

Agent creates resources Okteto can't track

This happens when the agent uses kubectl, helm, or other tools directly instead of okteto deploy. Resources created outside of Okteto's deploy pipeline won't appear in the Dashboard and won't be cleaned up automatically.

Make sure all deployments go through okteto deploy. If you need custom commands, add them to the deploy section of okteto.yaml.