Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
fix: only perform auto pairing on edge edgent not direct (#2622)
Kyle Mendellac12462e7f19
diff --git a/AGENTS.md b/AGENTS.mdindex 7ea5e3ca3..f70255136 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -415,9 +415,13 @@ s.db.WithContext(ctx).Use `models.JSON` for arbitrary JSON fields and `models.StringSlice` for string arrays — both implement `driver.Valuer` and `sql.Scanner`.-## Edge Agent Mode+## Agent Modes-Edge agents connect to a central Arcane manager via WebSocket tunnel, allowing management of Docker hosts behind NAT/firewalls.+Arcane supports two agent modes with different connection directions.++### Edge mode++Edge agents connect outbound to a central manager via WebSocket or gRPC tunnel, allowing management of Docker hosts behind NAT/firewalls. The agent dials the manager; the manager never dials the agent.**Architecture:**@@ -438,10 +442,23 @@ ARCANE_AGENT_TOKEN=<api-key>- `heartbeat` / `heartbeat_ack`: Connection keepalive- `ws_start` / `ws_data` / `ws_close`: WebSocket streaming (logs, stats)+### Direct mode++Direct agents are passive: the agent runs an HTTP server on TCP 3553 and the manager initiates every request. Requires inbound TCP 3553 on the agent host, but no outbound path back to the manager. Suits one-way network setups (SSH forward tunnels, restricted-outbound hosts).++**Configuration** (agent side):++```bash+ARCANE_AGENT_MODE=true+ARCANE_AGENT_TOKEN=<api-key>+```++`ARCANE_MANAGER_API_URL` is **not** used in Direct mode — the agent never dials out. Pairing completes when the manager's periodic health-check (every 2 min by default) reaches the agent.+**When implementing agent features:**- Check `cfg.AgentMode` to skip manager-only logic (e.g., environment health checks)-- Agent auto-pairs with manager on startup if token is configured+- Edge agents auto-pair on startup; Direct agents are paired by the manager's reachability check- Edge connections are stateless — each request is independent## AI-Assisted Contributionsdiff --git a/CONTEXT.md b/CONTEXT.mdindex 59784420c..cfad7fecd 100644--- a/CONTEXT.md+++ b/CONTEXT.md@@ -28,6 +28,10 @@ A headless Arcane process running near a Docker host. It accepts manager requestAn agent that connects outbound to the Arcane Manager over the edge transport so Docker hosts behind NAT or firewalls can be managed.+### Direct Agent++An agent that runs as a passive HTTP server on TCP 3553. The manager initiates all connections; the agent never dials out. Suited to one-way network paths (e.g. SSH forward tunnels, restricted-outbound hosts).+### ProjectAn Arcane-managed Docker Compose project stored under the configured projects directory. Projects have compose files, optional env files, persisted metadata, deployment state, and related Docker resources.diff --git a/backend/internal/bootstrap/bootstrap.go b/backend/internal/bootstrap/bootstrap.goindex de4a69640..62ae61c53 100644--- a/backend/internal/bootstrap/bootstrap.go+++ b/backend/internal/bootstrap/bootstrap.go@@ -209,11 +209,16 @@ func initializeStartupState(appCtx context.Context, cfg *config.Config, appServi)startup.CleanupUnknownSettings(appCtx, appServices.Settings)- // Handle agent auto-pairing with API key.- if cfg.AgentMode && cfg.AgentToken != "" && cfg.ManagerApiUrl != "" {+ // Auto-pair only applies in Edge mode (where the agent's outbound tunnel is the+ // only path to the manager). Direct mode is passive — the manager dials the agent's+ // HTTP server on TCP 3553, and the manager-side health-check promotes the env to+ // Online once reachability is confirmed.+ if cfg.AgentMode && cfg.EdgeAgent && cfg.AgentToken != "" && cfg.ManagerApiUrl != "" {if err := handleAgentBootstrapPairing(appCtx, cfg, httpClient); err != nil {slog.WarnContext(appCtx, "Failed to auto-pair agent with manager", "error", err)}+ } else if cfg.AgentMode && !cfg.EdgeAgent {+ slog.InfoContext(appCtx, "Direct mode active: agent operates as a passive HTTP server; no outbound connection to manager required")}}diff --git a/backend/internal/services/environment_service.go b/backend/internal/services/environment_service.goindex aafc39567..1a9ac3469 100644--- a/backend/internal/services/environment_service.go+++ b/backend/internal/services/environment_service.go@@ -824,15 +824,22 @@ func (s *EnvironmentService) testLocalDockerConnection(ctx context.Context, id s}func (s *EnvironmentService) updateEnvironmentStatusInternal(ctx context.Context, id, status string) error {- // Don't update status for pending environments - they're waiting for agent pairingvar currentEnv models.Environment- if err := s.db.WithContext(ctx).Select("status").Where("id = ?", id).First(¤tEnv).Error; err != nil {+ if err := s.db.WithContext(ctx).Select("status", "is_edge").Where("id = ?", id).First(¤tEnv).Error; err != nil {return fmt.Errorf("failed to check environment status: %w", err)}if currentEnv.Status == string(models.EnvironmentStatusPending) {- slog.DebugContext(ctx, "skipping status update for pending environment", "environment_id", id)- return nil+ // Edge envs must complete pairing via the agent's outbound tunnel — manager+ // can't dial them directly, so a manager-side reachability check means nothing.+ // Direct envs are reachable from the manager, so a successful health check IS+ // the pairing signal. Don't promote on offline/error ticks though, or a transient+ // blip during initial setup would flip the env out of pending.+ if currentEnv.IsEdge || status != string(models.EnvironmentStatusOnline) {+ slog.DebugContext(ctx, "skipping status update for pending environment", "environment_id", id)+ return nil+ }+ slog.InfoContext(ctx, "promoted pending direct environment to online via reachability check", "environment_id", id)}now := time.Now()diff --git a/backend/internal/services/environment_service_test.go b/backend/internal/services/environment_service_test.goindex a2e0b4139..1c47c95d3 100644--- a/backend/internal/services/environment_service_test.go+++ b/backend/internal/services/environment_service_test.go@@ -406,6 +406,57 @@ func TestEnvironmentService_UpdateEnvironmentConnectionState(t *testing.T) {require.Equal(t, *lastSeen, *env.LastSeen)}+func TestEnvironmentService_UpdateEnvironmentStatusInternal_PromotesPendingDirectEnv(t *testing.T) {+ ctx := context.Background()+ db := setupEnvironmentServiceTestDB(t)+ svc := NewEnvironmentService(db, nil, nil, nil, nil, nil)++ createTestEnvironmentWithState(t, db, "direct-pending", "http://agent:3553", string(models.EnvironmentStatusPending), false, nil)++ require.NoError(t, svc.updateEnvironmentStatusInternal(ctx, "direct-pending", string(models.EnvironmentStatusOnline)))++ var env models.Environment+ require.NoError(t, db.WithContext(ctx).Where("id = ?", "direct-pending").First(&env).Error)+ require.Equal(t, string(models.EnvironmentStatusOnline), env.Status)+ require.NotNil(t, env.LastSeen)+}++func TestEnvironmentService_UpdateEnvironmentStatusInternal_DoesNotDemotePendingDirectEnvOnFailedTick(t *testing.T) {+ ctx := context.Background()+ db := setupEnvironmentServiceTestDB(t)+ svc := NewEnvironmentService(db, nil, nil, nil, nil, nil)++ createTestEnvironmentWithState(t, db, "direct-pending", "http://agent:3553", string(models.EnvironmentStatusPending), false, nil)++ // A transient health-check failure before pairing completes must NOT flip a+ // pending Direct env to offline/error — the env should stay pending so a later+ // successful tick can still promote it to online.+ require.NoError(t, svc.updateEnvironmentStatusInternal(ctx, "direct-pending", string(models.EnvironmentStatusOffline)))+ require.NoError(t, svc.updateEnvironmentStatusInternal(ctx, "direct-pending", string(models.EnvironmentStatusError)))++ var env models.Environment+ require.NoError(t, db.WithContext(ctx).Where("id = ?", "direct-pending").First(&env).Error)+ require.Equal(t, string(models.EnvironmentStatusPending), env.Status)+ require.Nil(t, env.LastSeen)+}++func TestEnvironmentService_UpdateEnvironmentStatusInternal_LeavesPendingEdgeEnvAlone(t *testing.T) {+ ctx := context.Background()+ db := setupEnvironmentServiceTestDB(t)+ svc := NewEnvironmentService(db, nil, nil, nil, nil, nil)++ createTestEnvironmentWithState(t, db, "edge-pending", "edge://agent", string(models.EnvironmentStatusPending), true, nil)++ // Edge envs in pending must complete pairing via the agent's outbound tunnel;+ // a manager-side reachability tick must NOT promote them.+ require.NoError(t, svc.updateEnvironmentStatusInternal(ctx, "edge-pending", string(models.EnvironmentStatusOnline)))++ var env models.Environment+ require.NoError(t, db.WithContext(ctx).Where("id = ?", "edge-pending").First(&env).Error)+ require.Equal(t, string(models.EnvironmentStatusPending), env.Status)+ require.Nil(t, env.LastSeen)+}+func TestEnvironmentService_ResolveEdgeEnvironmentByToken_CachesAndInvalidatesOnUpdate(t *testing.T) {ctx := context.Background()db := setupEnvironmentServiceTestDB(t)