Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

Add remote packages, services, sudo, job streaming and capability re-probe

Juan Denise71099a4e9c5
diff --git a/agent/internal/agent/agent.go b/agent/internal/agent/agent.go
index 4446b30c..fad17188 100644
--- a/agent/internal/agent/agent.go
+++ b/agent/internal/agent/agent.go
@@ -26,6 +26,7 @@ import (
"github.com/serverkit/agent/internal/events"
"github.com/serverkit/agent/internal/gui"
"github.com/serverkit/agent/internal/ipc"
+ "github.com/serverkit/agent/internal/jobs"
"github.com/serverkit/agent/internal/logger"
"github.com/serverkit/agent/internal/metrics"
"github.com/serverkit/agent/internal/terminal"
@@ -54,6 +55,13 @@ type Agent struct {
sampler *metricSampler
events *events.Store
gui *gui.SDK
+ jobs *jobs.Registry
+
+ // pkgLock serializes package-manager mutations (install / remove /
+ // upgrade / update_cache) inside a single agent so two concurrent
+ // requests don't race on dpkg/rpm locks. Reads (list_installed,
+ // search, info) don't take the lock.
+ pkgLock sync.Mutex
// Active subscriptions
subscriptions map[string]context.CancelFunc
@@ -62,10 +70,24 @@ type Agent struct {
// Command handlers
handlers map[string]CommandHandler
- // Capabilities probed once at startup. Sent to the panel each time
- // the transport reconnects (so a panel restart picks them up
- // without waiting for the agent to also restart).
+ // Capabilities probed at startup, refreshable via
+ // agent:recapabilities. Sent to the panel each time the transport
+ // reconnects (so a panel restart picks them up without waiting for
+ // the agent to also restart). capMu guards reads/writes during a
+ // re-probe so we don't ship a half-mutated payload.
capabilities protocol.CapabilitiesMessage
+ capMu sync.Mutex
+ reprobing bool
+
+ // sudoMode is the agent's privilege-escalation mode (root /
+ // passwordless / unavailable). Probed once at startup; if the user
+ // adds sudoers config later, agent:recapabilities re-probes.
+ sudoMode SudoMode
+
+ // systemdJSON tracks whether `systemctl --output=json` is supported
+ // on this host (systemd >= 244). Probed lazily on first use.
+ systemdJSON bool
+ systemdJSONOnce sync.Once
// Lifecycle tracking
startTime time.Time
@@ -136,6 +158,7 @@ func New(cfg *config.Config, log *logger.Logger) (*Agent, error) {
sampler: newMetricSampler(300), // 5 min @ 1 Hz
events: eventStore,
gui: gui.New(log),
+ jobs: jobs.NewRegistry(64),
subscriptions: make(map[string]context.CancelFunc),
handlers: make(map[string]CommandHandler),
startTime: time.Now(),
@@ -146,7 +169,7 @@ func New(cfg *config.Config, log *logger.Logger) (*Agent, error) {
// every reconnect without re-probing. Docker availability is taken
// from whether NewClient succeeded above; the capability layer
// doesn't redo that work.
- probeCtx, probeCancel := context.WithTimeout(context.Background(), 5*time.Second)
+ probeCtx, probeCancel := context.WithTimeout(context.Background(), 10*time.Second)
agent.capabilities = capabilities.Probe(
probeCtx,
log,
@@ -154,7 +177,11 @@ func New(cfg *config.Config, log *logger.Logger) (*Agent, error) {
cfg.Features.FileAccess,
cfg.Security.AllowedPaths,
)
+ agent.sudoMode = probeSudoMode(probeCtx)
+ agent.capabilities.Sudo = string(agent.sudoMode)
+ agent.capabilities.ProbedAt = time.Now().UnixMilli()
probeCancel()
+ log.Info("Sudo probe complete", "mode", agent.sudoMode)
// Register command handlers
agent.registerHandlers()
@@ -178,24 +205,29 @@ func (a *Agent) registerHandlers() {
if a.docker != nil {
a.handlers[protocol.ActionDockerContainerList] = a.handleDockerContainerList
a.handlers[protocol.ActionDockerContainerInspect] = a.handleDockerContainerInspect
+ a.handlers[protocol.ActionDockerContainerCreate] = a.handleDockerContainerCreate
a.handlers[protocol.ActionDockerContainerStart] = a.handleDockerContainerStart
a.handlers[protocol.ActionDockerContainerStop] = a.handleDockerContainerStop
a.handlers[protocol.ActionDockerContainerRestart] = a.handleDockerContainerRestart
a.handlers[protocol.ActionDockerContainerRemove] = a.handleDockerContainerRemove
a.handlers[protocol.ActionDockerContainerStats] = a.handleDockerContainerStats
a.handlers[protocol.ActionDockerContainerLogs] = a.handleDockerContainerLogs
+ a.handlers[protocol.ActionDockerContainerExec] = a.handleDockerContainerExec
// Docker image commands
a.handlers[protocol.ActionDockerImageList] = a.handleDockerImageList
a.handlers[protocol.ActionDockerImagePull] = a.handleDockerImagePull
a.handlers[protocol.ActionDockerImageRemove] = a.handleDockerImageRemove
+ a.handlers[protocol.ActionDockerImageBuild] = a.handleDockerImageBuild
// Docker volume commands
a.handlers[protocol.ActionDockerVolumeList] = a.handleDockerVolumeList
+ a.handlers[protocol.ActionDockerVolumeCreate] = a.handleDockerVolumeCreate
a.handlers[protocol.ActionDockerVolumeRemove] = a.handleDockerVolumeRemove
// Docker network commands
a.handlers[protocol.ActionDockerNetworkList] = a.handleDockerNetworkList
+ a.handlers[protocol.ActionDockerNetworkCreate] = a.handleDockerNetworkCreate
a.handlers[protocol.ActionDockerNetworkRemove] = a.handleDockerNetworkRemove
// Docker compose commands
@@ -256,16 +288,26 @@ func (a *Agent) registerHandlers() {
a.handlers[protocol.ActionPackagesInstall] = a.handlePackagesInstall
a.handlers[protocol.ActionPackagesRemove] = a.handlePackagesRemove
a.handlers[protocol.ActionPackagesListInstalled] = a.handlePackagesListInstalled
+ a.handlers[protocol.ActionPackagesUpdateCache] = a.handlePackagesUpdateCache
+ a.handlers[protocol.ActionPackagesInstallAsync] = a.handlePackagesInstallAsync
+ a.handlers[protocol.ActionPackagesUpgrade] = a.handlePackagesUpgrade
+ a.handlers[protocol.ActionPackagesSearch] = a.handlePackagesSearch
+ a.handlers[protocol.ActionPackagesInfo] = a.handlePackagesInfo
a.handlers[protocol.ActionSystemdStatus] = a.handleSystemdStatus
a.handlers[protocol.ActionSystemdStart] = a.handleSystemdStart
a.handlers[protocol.ActionSystemdStop] = a.handleSystemdStop
a.handlers[protocol.ActionSystemdRestart] = a.handleSystemdRestart
a.handlers[protocol.ActionSystemdEnable] = a.handleSystemdEnable
a.handlers[protocol.ActionSystemdDisable] = a.handleSystemdDisable
+ a.handlers[protocol.ActionSystemdDaemonReload] = a.handleSystemdDaemonReload
+ a.handlers[protocol.ActionSystemdListUnits] = a.handleSystemdListUnits
+ a.handlers[protocol.ActionSystemdLogs] = a.handleSystemdLogs
+ a.handlers[protocol.ActionSystemdLogsFollow] = a.handleSystemdLogsFollow
a.handlers[protocol.ActionSystemExec] = a.handleSystemExec
// Agent commands
a.handlers[protocol.ActionAgentUpdate] = a.handleAgentUpdate
+ a.handlers[protocol.ActionAgentRecapabilities] = a.handleAgentRecapabilities
// GUI SDK — primitives that panel extensions (serverkit-gui, etc.)
// compose into desktop-streaming or synthetic-UI features. Always
@@ -490,22 +532,30 @@ func (a *Agent) connectionWatcher(ctx context.Context) {
// metadata; missing ones just mean an agent doesn't show up in feature
// pickers until the next reconnect.
func (a *Agent) sendCapabilities() {
+ a.capMu.Lock()
+ caps := a.capabilities
+ a.capMu.Unlock()
msg := protocol.CapabilitiesMessage{
- Message: protocol.NewMessage(protocol.TypeCapabilities, auth.GenerateNonce()),
- Capabilities: a.capabilities.Capabilities,
- Platform: a.capabilities.Platform,
- Distro: a.capabilities.Distro,
- DistroVersion: a.capabilities.DistroVersion,
- Runtimes: a.capabilities.Runtimes,
- AllowedPaths: a.capabilities.AllowedPaths,
+ Message: protocol.NewMessage(protocol.TypeCapabilities, auth.GenerateNonce()),
+ Capabilities: caps.Capabilities,
+ Platform: caps.Platform,
+ Distro: caps.Distro,
+ DistroVersion: caps.DistroVersion,
+ Runtimes: caps.Runtimes,
+ AllowedPaths: caps.AllowedPaths,
+ Sudo: caps.Sudo,
+ RuntimeManagers: caps.RuntimeManagers,
+ SystemdJSON: caps.SystemdJSON,
+ ProbedAt: caps.ProbedAt,
}
if err := a.ws.Send(msg); err != nil {
a.log.Warn("Failed to send capabilities", "error", err)
return
}
a.log.Debug("Sent capabilities to panel",
- "platform", a.capabilities.Platform,
- "distro", a.capabilities.Distro,
+ "platform", caps.Platform,
+ "distro", caps.Distro,
+ "sudo", caps.Sudo,
)
}
@@ -639,6 +689,20 @@ func (a *Agent) handleSubscribe(data []byte) {
a.log.Info("Subscribing to channel", "channel", sub.Channel)
+ // Replay any buffered events for job channels so a panel that
+ // subscribed mid-flight (or just after the job finished) still sees
+ // the full progress history. Replay before installing the
+ // subscription record so a brand-new "live" event can't get
+ // interleaved before the replay.
+ if job := a.jobs.LookupByChannel(sub.Channel); job != nil {
+ for _, ev := range job.Replay() {
+ if err := a.ws.SendStream(sub.Channel, ev); err != nil {
+ a.log.Warn("Failed to replay job event", "channel", sub.Channel, "error", err)
+ break
+ }
+ }
+ }
+
// Create cancellable context for this subscription
ctx, cancel := context.WithCancel(context.Background())
diff --git a/agent/internal/agent/docker_extra_handlers.go b/agent/internal/agent/docker_extra_handlers.go
new file mode 100644
index 00000000..002193d3
--- /dev/null
+++ b/agent/internal/agent/docker_extra_handlers.go
@@ -0,0 +1,270 @@
+package agent
+
+// Phase 1e — fill in the docker actions that were declared in the
+// protocol but never wired to handlers: container:create,
+// container:exec, image:build, volume:create, network:create. The
+// existing handlers (start/stop/list/inspect/logs/stats, image
+// list/pull/remove, compose) live in agent.go alongside their
+// containers; we put the new ones in their own file to keep the diff
+// reviewable.
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "os/exec"
+ "path/filepath"
+ "strings"
+ "time"
+
+ "github.com/serverkit/agent/internal/docker"
+ "github.com/serverkit/agent/internal/jobs"
+)
+
+// validateImageName rejects shell metacharacters in user-supplied image
+// references. Docker is generally tolerant about what it accepts as a
+// tag, but we don't want a "registry.example.com/img;rm -rf /" landing
+// in argv even if exec.Command is safe — it's a clearer error to
+// reject up front.
+func validateImageName(s string) error {
+ s = strings.TrimSpace(s)
+ if s == "" {
+ return errors.New("image is required")
+ }
+ if strings.ContainsAny(s, ";&|`$<>\n\r\"'\\") {
+ return fmt.Errorf("invalid image: %q", s)
+ }
+ return nil
+}
+
+func validateContainerID(s string) error {
+ s = strings.TrimSpace(s)
+ if s == "" {
+ return errors.New("container is required")
+ }
+ if strings.ContainsAny(s, ";&|`$<>\n\r\"'\\ /") {
+ return fmt.Errorf("invalid container id/name: %q", s)
+ }
+ return nil
+}
+
+// ───── docker:container:create ────────────────────────────────────
+
+func (a *Agent) handleDockerContainerCreate(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ if a.docker == nil {
+ return nil, errors.New("docker not available")
+ }
+ var spec docker.ContainerCreateSpec
+ if err := json.Unmarshal(params, &spec); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ if err := validateImageName(spec.Image); err != nil {
+ return nil, err
+ }
+ // v1 reject privileged-ish fields. They round-trip in the JSON but
+ // are not part of ContainerCreateSpec — defensively check raw params
+ // to fail loudly when a caller tries to set them. The struct-shaped
+ // check is at the field level above.
+ var raw map[string]interface{}
+ _ = json.Unmarshal(params, &raw)
+ for _, banned := range []string{"privileged", "cap_add", "devices"} {
+ if _, ok := raw[banned]; ok {
+ return nil, fmt.Errorf("%s is not supported in v1 container:create", banned)
+ }
+ }
+ id, err := a.docker.CreateContainer(ctx, spec)
+ if err != nil {
+ return nil, fmt.Errorf("create container: %w", err)
+ }
+ return map[string]interface{}{
+ "id": id,
+ "name": spec.Name,
+ "image": spec.Image,
+ "status": "created",
+ }, nil
+}
+
+// ───── docker:container:exec ──────────────────────────────────────
+
+func (a *Agent) handleDockerContainerExec(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ if a.docker == nil {
+ return nil, errors.New("docker not available")
+ }
+ var p struct {
+ Container string `json:"container"`
+ Cmd []string `json:"cmd"`
+ User string `json:"user"`
+ WorkingDir string `json:"working_dir"`
+ TimeoutSeconds int `json:"timeout_seconds"`
+ }
+ if err := json.Unmarshal(params, &p); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ if err := validateContainerID(p.Container); err != nil {
+ return nil, err
+ }
+ if len(p.Cmd) == 0 {
+ return nil, errors.New("cmd is required")
+ }
+ timeout := time.Duration(p.TimeoutSeconds) * time.Second
+ if timeout <= 0 || timeout > 5*time.Minute {
+ timeout = 60 * time.Second
+ }
+ cctx, cancel := context.WithTimeout(ctx, timeout)
+ defer cancel()
+ res, err := a.docker.ExecContainer(cctx, p.Container, p.Cmd, p.User, p.WorkingDir, 1024*1024)
+ if err != nil {
+ return nil, fmt.Errorf("exec: %w", err)
+ }
+ return res, nil
+}
+
+// ───── docker:image:build ─────────────────────────────────────────
+
+func (a *Agent) handleDockerImageBuild(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ if a.docker == nil {
+ return nil, errors.New("docker not available")
+ }
+ var spec docker.ImageBuildSpec
+ if err := json.Unmarshal(params, &spec); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ if err := validateImageName(spec.Tag); err != nil {
+ return nil, fmt.Errorf("tag: %w", err)
+ }
+ abs, err := filepath.Abs(spec.ContextPath)
+ if err != nil {
+ return nil, fmt.Errorf("context_path: %w", err)
+ }
+ if !a.contextPathAllowed(abs) {
+ return nil, fmt.Errorf("context_path %q is not under any allowed root", abs)
+ }
+ spec.ContextPath = abs
+
+ job := a.jobs.New(500)
+ go a.runDockerBuildJob(job, spec)
+ return map[string]interface{}{
+ "job_id": job.ID,
+ "channel": job.Channel,
+ "tag": spec.Tag,
+ }, nil
+}
+
+func (a *Agent) contextPathAllowed(path string) bool {
+ for _, root := range a.cfg.Security.AllowedPaths {
+ ar, err := filepath.Abs(root)
+ if err != nil {
+ continue
+ }
+ // path must be under ar (or equal). Use Rel to detect ".." escapes.
+ rel, err := filepath.Rel(ar, path)
+ if err != nil {
+ continue
+ }
+ if rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+ return true
+ }
+ }
+ return false
+}
+
+func (a *Agent) runDockerBuildJob(job *jobs.Job, spec docker.ImageBuildSpec) {
+ exit := 0
+ emitDone := func(errStr string) {
+ _ = job.Push(a.ws, jobs.Event{
+ Phase: jobs.PhaseDone,
+ ExitCode: &exit,
+ Error: errStr,
+ Extra: map[string]interface{}{"tag": spec.Tag},
+ })
+ }
+ cctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
+ defer cancel()
+ cmd, err := a.docker.BuildImageCmd(cctx, spec)
+ if err != nil {
+ exit = -1
+ emitDone(err.Error())
+ return
+ }
+ _ = job.Push(a.ws, jobs.Event{Phase: jobs.PhaseStart, Message: fmt.Sprintf("docker build -t %s", spec.Tag)})
+ if err := streamCmdOutput(cmd, job, a.ws); err != nil {
+ exit = -1
+ emitDone(err.Error())
+ return
+ }
+ if cerr := cmd.Wait(); cerr != nil {
+ exit = exitCodeOfCmd(cerr)
+ if exit == 0 {
+ exit = -1
+ }
+ emitDone(cerr.Error())
+ return
+ }
+ emitDone("")
+}
+
+// exitCodeOfCmd duplicates exitCodeOf from package_handlers.go to
+// avoid an import cycle in this file. They're trivial enough that the
+// duplication is cheaper than refactoring callers.
+func exitCodeOfCmd(err error) int {
+ var ee *exec.ExitError
+ if errors.As(err, &ee) {
+ return ee.ExitCode()
+ }
+ return -1
+}
+
+// ───── docker:volume:create ───────────────────────────────────────
+
+func (a *Agent) handleDockerVolumeCreate(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ if a.docker == nil {
+ return nil, errors.New("docker not available")
+ }
+ var p struct {
+ Name string `json:"name"`
+ Driver string `json:"driver"`
+ Labels map[string]string `json:"labels"`
+ }
+ if err := json.Unmarshal(params, &p); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ if strings.TrimSpace(p.Name) == "" {
+ return nil, errors.New("name is required")
+ }
+ if strings.ContainsAny(p.Name, ";&|`$<>\n\r\"'\\ /") {
+ return nil, fmt.Errorf("invalid volume name: %q", p.Name)
+ }
+ vol, err := a.docker.CreateVolume(ctx, p.Name, p.Driver, p.Labels)
+ if err != nil {
+ return nil, fmt.Errorf("create volume: %w", err)
+ }
+ return vol, nil
+}
+
+// ───── docker:network:create ──────────────────────────────────────
+
+func (a *Agent) handleDockerNetworkCreate(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ if a.docker == nil {
+ return nil, errors.New("docker not available")
+ }
+ var spec docker.NetworkCreateSpec
+ if err := json.Unmarshal(params, &spec); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ if strings.TrimSpace(spec.Name) == "" {
+ return nil, errors.New("name is required")
+ }
+ if strings.ContainsAny(spec.Name, ";&|`$<>\n\r\"'\\ /") {
+ return nil, fmt.Errorf("invalid network name: %q", spec.Name)
+ }
+ id, err := a.docker.CreateNetwork(ctx, spec)
+ if err != nil {
+ return nil, fmt.Errorf("create network: %w", err)
+ }
+ return map[string]interface{}{
+ "id": id,
+ "name": spec.Name,
+ "driver": spec.Driver,
+ }, nil
+}
diff --git a/agent/internal/agent/package_handlers.go b/agent/internal/agent/package_handlers.go
new file mode 100644
index 00000000..407920d1
--- /dev/null
+++ b/agent/internal/agent/package_handlers.go
@@ -0,0 +1,564 @@
+package agent
+
+// Phase 1c additions — package manager actions beyond the original
+// install/remove/list trio: search, info, update-cache, plus a
+// streaming variant of install/upgrade that emits progress on a job
+// channel for the Packages tab and one-click templates.
+//
+// The existing handlePackagesInstall (single-name, synchronous,
+// idempotent short-circuit) is left alone so the workflow engine's
+// agent_command callers still get a structured result. New callers
+// wanting progress streaming use packages:install_async / packages:upgrade.
+
+import (
+ "bufio"
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "os/exec"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/serverkit/agent/internal/jobs"
+)
+
+// extendedPackageManager carries the new-action arg patterns alongside
+// the existing packageManager. We don't fold these into packageManager
+// itself to keep the original definition (and its callers) untouched.
+type extendedPackageManager struct {
+ bin string
+ updateCache []string
+ upgradeAll []string
+ upgradePkg []string // appended with package name(s)
+ searchCmd []string
+ infoCmd []string // appended with name
+}
+
+func extendedFor(pm *packageManager) *extendedPackageManager {
+ switch pm.bin {
+ case "apt-get":
+ return &extendedPackageManager{
+ bin: "apt-get",
+ updateCache: []string{"update"},
+ upgradeAll: []string{"upgrade", "-y", "-o", "Dpkg::Options::=--force-confold"},
+ upgradePkg: []string{"install", "--only-upgrade", "-y", "-o", "Dpkg::Options::=--force-confold"},
+ searchCmd: []string{"search"}, // run via apt-cache below
+ infoCmd: []string{"show"}, // run via apt-cache below
+ }
+ case "dnf", "yum":
+ return &extendedPackageManager{
+ bin: pm.bin,
+ updateCache: []string{"check-update"},
+ upgradeAll: []string{"upgrade", "-y"},
+ upgradePkg: []string{"upgrade", "-y"},
+ searchCmd: []string{"search"},
+ infoCmd: []string{"info"},
+ }
+ case "apk":
+ return &extendedPackageManager{
+ bin: "apk",
+ updateCache: []string{"update"},
+ upgradeAll: []string{"upgrade"},
+ upgradePkg: []string{"upgrade"},
+ searchCmd: []string{"search", "-v"},
+ infoCmd: []string{"info"},
+ }
+ case "pacman":
+ return &extendedPackageManager{
+ bin: "pacman",
+ updateCache: []string{"-Sy"},
+ upgradeAll: []string{"-Syu", "--noconfirm"},
+ upgradePkg: []string{"-S", "--noconfirm"},
+ searchCmd: []string{"-Ss"},
+ infoCmd: []string{"-Si"},
+ }
+ case "zypper":
+ return &extendedPackageManager{
+ bin: "zypper",
+ updateCache: []string{"refresh"},
+ upgradeAll: []string{"update", "-y"},
+ upgradePkg: []string{"update", "-y"},
+ searchCmd: []string{"se"},
+ infoCmd: []string{"info"},
+ }
+ }
+ return nil
+}
+
+// ───── packages:update_cache ──────────────────────────────────────
+
+func (a *Agent) handlePackagesUpdateCache(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ pm, err := detectPackageManager()
+ if err != nil {
+ return nil, err
+ }
+ ext := extendedFor(pm)
+ if ext == nil {
+ return nil, fmt.Errorf("update_cache: manager %q not supported", pm.bin)
+ }
+ a.pkgLock.Lock()
+ defer a.pkgLock.Unlock()
+
+ cctx, cancel := context.WithTimeout(ctx, 2*time.Minute)
+ defer cancel()
+ cmd, err := sudoCommandContext(cctx, a.sudoMode, ext.bin, ext.updateCache...)
+ if err != nil {
+ return nil, err
+ }
+ out, err := cmd.CombinedOutput()
+ tail := truncate(string(out), 4096)
+ if err != nil && !isCheckUpdateExit100(ext.bin, err) {
+ // dnf check-update returns 100 when updates are available; that
+ // isn't a failure, just an "actionable" exit. Anything else is
+ // treated as a real error.
+ if classifySudoError(string(out)) {
+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)
+ }
+ return nil, fmt.Errorf("%s %s: %w (%s)", ext.bin, strings.Join(ext.updateCache, " "), err, tail)
+ }
+ return map[string]interface{}{
+ "manager": ext.bin,
+ "output": tail,
+ }, nil
+}
+
+// dnf check-update conventionally exits 100 when there are updates
+// pending, 0 when nothing to do. We treat both as success.
+func isCheckUpdateExit100(bin string, err error) bool {
+ if bin != "dnf" && bin != "yum" {
+ return false
+ }
+ var ee *exec.ExitError
+ if errors.As(err, &ee) {
+ return ee.ExitCode() == 100
+ }
+ return false
+}
+
+// ───── packages:search ────────────────────────────────────────────
+
+func (a *Agent) handlePackagesSearch(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ var p struct {
+ Query string `json:"query"`
+ Limit int `json:"limit"`
+ }
+ if err := json.Unmarshal(params, &p); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ q := strings.TrimSpace(p.Query)
+ if q == "" {
+ return nil, errors.New("query is required")
+ }
+ if err := validatePackageName(q); err != nil {
+ // Reject metachars; reuse the install validator since search
+ // goes straight to argv.
+ return nil, err
+ }
+ if p.Limit <= 0 || p.Limit > 500 {
+ p.Limit = 500
+ }
+
+ pm, err := detectPackageManager()
+ if err != nil {
+ return nil, err
+ }
+ ext := extendedFor(pm)
+ if ext == nil {
+ return nil, fmt.Errorf("search: manager %q not supported", pm.bin)
+ }
+
+ cctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+ defer cancel()
+
+ bin := ext.bin
+ args := append([]string{}, ext.searchCmd...)
+ if pm.bin == "apt-get" {
+ bin = "apt-cache"
+ }
+ args = append(args, q)
+ out, err := exec.CommandContext(cctx, bin, args...).CombinedOutput()
+ if err != nil && len(out) == 0 {
+ return nil, fmt.Errorf("%s %s: %w", bin, strings.Join(args, " "), err)
+ }
+ lines := splitNonEmptyLines(string(out))
+ if len(lines) > p.Limit {
+ lines = lines[:p.Limit]
+ }
+ return map[string]interface{}{
+ "manager": pm.bin,
+ "query": q,
+ "limit": p.Limit,
+ "results": lines,
+ }, nil
+}
+
+// ───── packages:info ──────────────────────────────────────────────
+
+func (a *Agent) handlePackagesInfo(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ var p struct {
+ Name string `json:"name"`
+ }
+ if err := json.Unmarshal(params, &p); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ if err := validatePackageName(p.Name); err != nil {
+ return nil, err
+ }
+ pm, err := detectPackageManager()
+ if err != nil {
+ return nil, err
+ }
+ ext := extendedFor(pm)
+ if ext == nil {
+ return nil, fmt.Errorf("info: manager %q not supported", pm.bin)
+ }
+
+ cctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+ defer cancel()
+ bin := ext.bin
+ if pm.bin == "apt-get" {
+ bin = "apt-cache"
+ }
+ args := append(append([]string{}, ext.infoCmd...), p.Name)
+ out, err := exec.CommandContext(cctx, bin, args...).CombinedOutput()
+ if err != nil && len(out) == 0 {
+ return nil, fmt.Errorf("%s %s: %w", bin, strings.Join(args, " "), err)
+ }
+ return map[string]interface{}{
+ "manager": pm.bin,
+ "name": p.Name,
+ "output": truncate(string(out), 16*1024),
+ }, nil
+}
+
+// ───── packages:install_async + packages:upgrade ─────────────────
+
+// installRequest is the shared param shape for install_async / upgrade.
+// Either Names (list) or Name (single) may be set; an empty Names with
+// All=true upgrades everything (only meaningful for upgrade).
+type installRequest struct {
+ Names []string `json:"names"`
+ Name string `json:"name"`
+ All bool `json:"all"`
+}
+
+func (r *installRequest) normalize() error {
+ if r.Name != "" {
+ r.Names = append(r.Names, r.Name)
+ }
+ for _, n := range r.Names {
+ if err := validatePackageName(n); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+
+// handlePackagesInstallAsync is a streaming variant of install: returns
+// {job_id, channel} immediately and emits per-line progress on the
+// channel. Idempotent like the sync variant — packages already
+// installed are skipped (we still emit a status event).
+func (a *Agent) handlePackagesInstallAsync(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ var p installRequest
+ if err := json.Unmarshal(params, &p); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ if err := p.normalize(); err != nil {
+ return nil, err
+ }
+ if len(p.Names) == 0 {
+ return nil, errors.New("at least one package name required")
+ }
+ pm, err := detectPackageManager()
+ if err != nil {
+ return nil, err
+ }
+ if a.sudoMode == SudoUnavailable {
+ return nil, errSudoRequired
+ }
+
+ job := a.jobs.New(200)
+ go a.runPackageInstallJob(job, pm, p.Names)
+ return map[string]interface{}{
+ "job_id": job.ID,
+ "channel": job.Channel,
+ }, nil
+}
+
+// handlePackagesUpgrade upgrades the named packages, or all packages
+// when All=true. Streams progress identically to install_async.
+func (a *Agent) handlePackagesUpgrade(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ var p installRequest
+ if err := json.Unmarshal(params, &p); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ if err := p.normalize(); err != nil {
+ return nil, err
+ }
+ if !p.All && len(p.Names) == 0 {
+ return nil, errors.New("either names[] or all=true required")
+ }
+ pm, err := detectPackageManager()
+ if err != nil {
+ return nil, err
+ }
+ ext := extendedFor(pm)
+ if ext == nil {
+ return nil, fmt.Errorf("upgrade: manager %q not supported", pm.bin)
+ }
+ if a.sudoMode == SudoUnavailable {
+ return nil, errSudoRequired
+ }
+
+ job := a.jobs.New(200)
+ go a.runPackageUpgradeJob(job, pm, ext, p.Names, p.All)
+ return map[string]interface{}{
+ "job_id": job.ID,
+ "channel": job.Channel,
+ }, nil
+}
+
+// runPackageInstallJob runs the apt/dnf/etc. install in the background,
+// streams output line-by-line on the job channel, and emits a final
+// done event with the structured result.
+func (a *Agent) runPackageInstallJob(job *jobs.Job, pm *packageManager, names []string) {
+ a.pkgLock.Lock()
+ defer a.pkgLock.Unlock()
+
+ exit := 0
+ emitDone := func(errStr string, installed []string) {
+ ev := jobs.Event{
+ Phase: jobs.PhaseDone,
+ ExitCode: &exit,
+ Error: errStr,
+ Extra: map[string]interface{}{
+ "manager": pm.bin,
+ "action": "install",
+ "installed": installed,
+ },
+ }
+ _ = job.Push(a.ws, ev)
+ }
+
+ // Skip already-installed packages.
+ probeCtx, probeCancel := context.WithTimeout(context.Background(), 30*time.Second)
+ var toInstall, alreadyInstalled []string
+ for _, n := range names {
+ if installed, _ := pm.isInstalled(probeCtx, n); installed {
+ alreadyInstalled = append(alreadyInstalled, n)
+ continue
+ }
+ toInstall = append(toInstall, n)
+ }
+ probeCancel()
+
+ if len(alreadyInstalled) > 0 {
+ _ = job.Push(a.ws, jobs.Event{
+ Phase: jobs.PhaseStatus,
+ Message: fmt.Sprintf("already installed: %s", strings.Join(alreadyInstalled, ", ")),
+ })
+ }
+ if len(toInstall) == 0 {
+ emitDone("", alreadyInstalled)
+ return
+ }
+
+ _ = job.Push(a.ws, jobs.Event{
+ Phase: jobs.PhaseStart,
+ Message: fmt.Sprintf("installing %d package(s) via %s", len(toInstall), pm.bin),
+ })
+
+ // Long-running command — bound at 15 minutes.
+ cctx, cancel := context.WithTimeout(context.Background(), 15*time.Minute)
+ defer cancel()
+ args := append(append([]string{}, pm.install...), toInstall...)
+ cmd, err := sudoCommandContext(cctx, a.sudoMode, pm.bin, args...)
+ if err != nil {
+ exit = -1
+ emitDone(err.Error(), nil)
+ return
+ }
+ if err := streamCmdOutput(cmd, job, a.ws); err != nil {
+ exit = -1
+ emitDone(err.Error(), nil)
+ return
+ }
+ if cerr := cmd.Wait(); cerr != nil {
+ exit = exitCodeOf(cerr)
+ if exit == 0 {
+ exit = -1
+ }
+ emitDone(cerr.Error(), nil)
+ return
+ }
+ emitDone("", append(alreadyInstalled, toInstall...))
+}
+
+func (a *Agent) runPackageUpgradeJob(job *jobs.Job, pm *packageManager, ext *extendedPackageManager, names []string, all bool) {
+ a.pkgLock.Lock()
+ defer a.pkgLock.Unlock()
+
+ exit := 0
+ emitDone := func(errStr string) {
+ ev := jobs.Event{
+ Phase: jobs.PhaseDone,
+ ExitCode: &exit,
+ Error: errStr,
+ Extra: map[string]interface{}{
+ "manager": pm.bin,
+ "action": "upgrade",
+ "all": all,
+ },
+ }
+ _ = job.Push(a.ws, ev)
+ }
+
+ cctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
+ defer cancel()
+
+ // apt: refresh the package index first so upgrade sees newly
+ // published versions. Other managers do this implicitly.
+ if pm.bin == "apt-get" {
+ updCmd, err := sudoCommandContext(cctx, a.sudoMode, ext.bin, ext.updateCache...)
+ if err != nil {
+ exit = -1
+ emitDone(err.Error())
+ return
+ }
+ if err := streamCmdOutput(updCmd, job, a.ws); err != nil {
+ exit = -1
+ emitDone(err.Error())
+ return
+ }
+ _ = updCmd.Wait()
+ }
+
+ var args []string
+ if all {
+ args = append([]string{}, ext.upgradeAll...)
+ } else {
+ args = append(append([]string{}, ext.upgradePkg...), names...)
+ }
+ cmd, err := sudoCommandContext(cctx, a.sudoMode, ext.bin, args...)
+ if err != nil {
+ exit = -1
+ emitDone(err.Error())
+ return
+ }
+ _ = job.Push(a.ws, jobs.Event{
+ Phase: jobs.PhaseStart,
+ Message: fmt.Sprintf("%s %s", ext.bin, strings.Join(args, " ")),
+ })
+ if err := streamCmdOutput(cmd, job, a.ws); err != nil {
+ exit = -1
+ emitDone(err.Error())
+ return
+ }
+ if cerr := cmd.Wait(); cerr != nil {
+ exit = exitCodeOf(cerr)
+ if exit == 0 {
+ exit = -1
+ }
+ emitDone(cerr.Error())
+ return
+ }
+ emitDone("")
+}
+
+// streamCmdOutput attaches a line-buffered stdout/stderr scanner to cmd
+// and pushes batches of lines on the job channel. Lines are flushed on
+// a 100ms window or 32-line threshold, whichever comes first, so the
+// panel sees steady progress without one event per line at high
+// throughput.
+//
+// Blocks until both pipes close, then returns. Caller is expected to
+// invoke cmd.Wait() afterwards to reap the process and get the exit
+// code. Returns an error only if cmd.Start fails or pipe setup fails.
+func streamCmdOutput(cmd *exec.Cmd, job *jobs.Job, s jobs.Streamer) error {
+ stdout, err := cmd.StdoutPipe()
+ if err != nil {
+ return err
+ }
+ stderr, err := cmd.StderrPipe()
+ if err != nil {
+ return err
+ }
+ if err := cmd.Start(); err != nil {
+ return err
+ }
+
+ lines := make(chan string, 256)
+ var wg sync.WaitGroup
+ wg.Add(2)
+ go scanLines(stdout, lines, &wg)
+ go scanLines(stderr, lines, &wg)
+
+ // Closer goroutine: once both scanners have returned, close the
+ // channel so the batcher knows there's no more input.
+ go func() {
+ wg.Wait()
+ close(lines)
+ }()
+
+ // Batcher: flush every 100ms or 32 lines. Runs synchronously so
+ // the caller can rely on "all output emitted before we return."
+ batch := make([]string, 0, 32)
+ flush := func() {
+ if len(batch) == 0 {
+ return
+ }
+ _ = job.Push(s, jobs.Event{Phase: jobs.PhaseLog, Lines: append([]string{}, batch...)})
+ batch = batch[:0]
+ }
+ ticker := time.NewTicker(100 * time.Millisecond)
+ defer ticker.Stop()
+ for {
+ select {
+ case ln, ok := <-lines:
+ if !ok {
+ flush()
+ return nil
+ }
+ batch = append(batch, ln)
+ if len(batch) >= 32 {
+ flush()
+ }
+ case <-ticker.C:
+ flush()
+ }
+ }
+}
+
+func scanLines(r io.ReadCloser, out chan<- string, wg *sync.WaitGroup) {
+ defer wg.Done()
+ defer r.Close()
+ sc := bufio.NewScanner(r)
+ sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+ for sc.Scan() {
+ out <- sc.Text()
+ }
+}
+
+func exitCodeOf(err error) int {
+ var ee *exec.ExitError
+ if errors.As(err, &ee) {
+ return ee.ExitCode()
+ }
+ return -1
+}
+
+func splitNonEmptyLines(s string) []string {
+ var out []string
+ for _, ln := range strings.Split(s, "\n") {
+ ln = strings.TrimRight(ln, "\r")
+ if strings.TrimSpace(ln) == "" {
+ continue
+ }
+ out = append(out, ln)
+ }
+ return out
+}
+
diff --git a/agent/internal/agent/recapabilities.go b/agent/internal/agent/recapabilities.go
new file mode 100644
index 00000000..a2e7ff37
--- /dev/null
+++ b/agent/internal/agent/recapabilities.go
@@ -0,0 +1,123 @@
+package agent
+
+// agent:recapabilities — re-runs the capability probe on demand. The
+// panel calls this after the user installs a runtime / sudoers entry /
+// new package manager, so new feature surfaces light up without a
+// service restart.
+//
+// Concurrent re-probes are common (the panel may fire one per server
+// detail page open) and the underlying probes spawn subprocesses, so
+// we guard with a coarse mutex: if a probe is already in flight we
+// return the cached set with reprobe="in_progress" instead of
+// queueing.
+
+import (
+ "context"
+ "encoding/json"
+ "time"
+
+ "github.com/serverkit/agent/internal/capabilities"
+ "github.com/serverkit/agent/pkg/protocol"
+)
+
+func (a *Agent) handleAgentRecapabilities(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ a.capMu.Lock()
+ if a.reprobing {
+ caps := a.capabilities
+ a.capMu.Unlock()
+ return map[string]interface{}{
+ "reprobe": "in_progress",
+ "capabilities": caps,
+ }, nil
+ }
+ a.reprobing = true
+ a.capMu.Unlock()
+ defer func() {
+ a.capMu.Lock()
+ a.reprobing = false
+ a.capMu.Unlock()
+ }()
+
+ // Use a fresh, bounded context — the caller's request timeout
+ // might be shorter than the probe takes, but we still want to
+ // finish so the next subscriber sees fresh state.
+ probeCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+ defer cancel()
+
+ // Clear the PATH lookup cache so newly installed binaries (e.g. the
+ // user just ran apt install nginx) are seen by this re-probe.
+ capabilities.ClearPathCache()
+
+ fresh := capabilities.Probe(
+ probeCtx,
+ a.log,
+ a.docker != nil,
+ a.cfg.Features.FileAccess,
+ a.cfg.Security.AllowedPaths,
+ )
+
+ // Re-probe sudo as well — the user may have added passwordless
+ // sudoers config since boot.
+ mode := probeSudoMode(probeCtx)
+ fresh.Sudo = string(mode)
+ fresh.ProbedAt = time.Now().UnixMilli()
+
+ // Capabilities are additive across re-probes: if the previous
+ // snapshot saw a feature the panel cared about, don't drop it just
+ // because a transient probe failed (e.g. dockerd briefly
+ // restarting). Only flip false→true here, never true→false.
+ a.capMu.Lock()
+ merged := mergeCapabilities(a.capabilities, fresh)
+ a.capabilities = merged
+ a.sudoMode = mode
+ a.capMu.Unlock()
+
+ // Push to the panel so the in-memory ConnectedAgent record updates
+ // without an explicit refetch.
+ a.sendCapabilities()
+
+ return map[string]interface{}{
+ "reprobe": "ok",
+ "capabilities": merged,
+ }, nil
+}
+
+// mergeCapabilities returns a payload where bool capabilities are the
+// OR of prev and fresh, runtime maps are unioned, and the "presence"
+// of optional fields prefers fresh values. Numeric/string fields like
+// distro version are taken from fresh because the host might have been
+// upgraded between probes.
+//
+// The asymmetry is deliberate: a transient probe failure (dockerd
+// briefly down, journalctl hung) shouldn't cause a panel-side feature
+// to disappear, but a real upgrade/install should be reflected. So we
+// only flip false→true here, never true→false. To force a clean view
+// the operator can restart the agent.
+func mergeCapabilities(prev, fresh protocol.CapabilitiesMessage) protocol.CapabilitiesMessage {
+ out := fresh
+ if out.Capabilities == nil {
+ out.Capabilities = protocol.Capabilities{}
+ }
+ for k, v := range prev.Capabilities {
+ if v && !out.Capabilities[k] {
+ out.Capabilities[k] = true
+ }
+ }
+ if out.Runtimes == nil {
+ out.Runtimes = map[string]string{}
+ }
+ for k, v := range prev.Runtimes {
+ if _, ok := out.Runtimes[k]; !ok && v != "" {
+ out.Runtimes[k] = v
+ }
+ }
+ if out.RuntimeManagers == nil {
+ out.RuntimeManagers = map[string]string{}
+ }
+ for k, v := range prev.RuntimeManagers {
+ if _, ok := out.RuntimeManagers[k]; !ok && v != "" {
+ out.RuntimeManagers[k] = v
+ }
+ }
+ return out
+}
diff --git a/agent/internal/agent/sudo.go b/agent/internal/agent/sudo.go
new file mode 100644
index 00000000..8fef5666
--- /dev/null
+++ b/agent/internal/agent/sudo.go
@@ -0,0 +1,124 @@
+package agent
+
+// Privilege escalation helpers. The agent's install script lays down a
+// dedicated `serverkit-agent` user, so handlers that touch system state
+// (systemctl, apt, dnf, journalctl on system journals) need to escalate
+// when the agent isn't running as root. We use passwordless sudo (-n)
+// so a hung password prompt can't tie up a request.
+//
+// The decision is made once at startup: probe whether `sudo -n true`
+// succeeds, cache the result, and surface it on the capabilities
+// payload as one of "root", "passwordless", or "unavailable" so the
+// panel can warn users *before* they try to install something.
+//
+// When the mode is "unavailable", privileged handlers fail fast with a
+// "sudo_required" error instead of spawning a subprocess that would
+// deadlock waiting for a password.
+
+import (
+ "context"
+ "errors"
+ "os"
+ "os/exec"
+ "runtime"
+ "strings"
+ "time"
+)
+
+// SudoMode describes how the agent escalates privileges.
+type SudoMode string
+
+const (
+ SudoRoot SudoMode = "root" // EUID == 0
+ SudoPasswordless SudoMode = "passwordless" // sudo -n works
+ SudoUnavailable SudoMode = "unavailable" // no escalation possible
+)
+
+// errSudoRequired is returned by privileged handlers when escalation
+// isn't available. Wrapped with extra context by the calling handler.
+var errSudoRequired = errors.New("sudo required: agent is running as a non-root user and passwordless sudo is not configured")
+
+// probeSudoMode determines the agent's escalation capability. Called
+// once at startup; the result is cached in Agent.sudoMode.
+func probeSudoMode(ctx context.Context) SudoMode {
+ if runtime.GOOS != "linux" {
+ // Non-linux hosts don't run the privileged handlers anyway —
+ // systemd/packages capabilities are gated off on those.
+ if isAdminWindows() {
+ return SudoRoot
+ }
+ return SudoUnavailable
+ }
+ if os.Geteuid() == 0 {
+ return SudoRoot
+ }
+ if _, err := exec.LookPath("sudo"); err != nil {
+ return SudoUnavailable
+ }
+ cctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+ defer cancel()
+ cmd := exec.CommandContext(cctx, "sudo", "-n", "true")
+ if err := cmd.Run(); err != nil {
+ return SudoUnavailable
+ }
+ return SudoPasswordless
+}
+
+// isAdminWindows is a placeholder: the privileged handlers are gated by
+// runtime.GOOS == "linux" anyway, so the only effect is the value
+// surfaced on the capabilities payload. Returning false everywhere on
+// Windows is safe.
+func isAdminWindows() bool { return false }
+
+// sudoCommandContext returns an exec.Cmd that runs `name args...` with
+// privilege escalation according to the agent's sudo mode. When the
+// mode is "unavailable", it returns nil and a sudo_required error —
+// callers must check both.
+//
+// The returned Cmd has DEBIAN_FRONTEND=noninteractive in its env so
+// dpkg conffile prompts don't hang installs in production. Callers
+// that need additional env should append to cmd.Env after the call.
+func sudoCommandContext(ctx context.Context, mode SudoMode, name string, args ...string) (*exec.Cmd, error) {
+ switch mode {
+ case SudoRoot:
+ cmd := exec.CommandContext(ctx, name, args...)
+ cmd.Env = privilegedEnv()
+ return cmd, nil
+ case SudoPasswordless:
+ full := append([]string{"-n", name}, args...)
+ cmd := exec.CommandContext(ctx, "sudo", full...)
+ cmd.Env = privilegedEnv()
+ return cmd, nil
+ default:
+ return nil, errSudoRequired
+ }
+}
+
+// privilegedEnv builds the env block used for privileged commands.
+// Inherits the parent process env and adds DEBIAN_FRONTEND so apt
+// upgrades don't stop on conffile prompts.
+func privilegedEnv() []string {
+ out := append([]string{}, os.Environ()...)
+ out = append(out, "DEBIAN_FRONTEND=noninteractive")
+ return out
+}
+
+// classifySudoError matches stderr text from a failed escalation
+// attempt and returns true when sudo specifically refused (password
+// required, terminal required, no permission). Used to wrap downstream
+// errors with a clean "sudo_required" code instead of leaking the raw
+// sudo banner to the panel.
+func classifySudoError(stderr string) bool {
+ low := strings.ToLower(stderr)
+ for _, marker := range []string{
+ "a password is required",
+ "a terminal is required",
+ "sudo: not allowed",
+ "sudo: must be setuid root",
+ } {
+ if strings.Contains(low, marker) {
+ return true
+ }
+ }
+ return false
+}
diff --git a/agent/internal/agent/systemd_handlers.go b/agent/internal/agent/systemd_handlers.go
new file mode 100644
index 00000000..5cb7c9df
--- /dev/null
+++ b/agent/internal/agent/systemd_handlers.go
@@ -0,0 +1,363 @@
+package agent
+
+// Phase 1c additions — systemd actions beyond status/start/stop/restart/
+// enable/disable: daemon-reload, list-units, journal logs (bounded fetch
+// and follow-stream variants).
+//
+// list-units prefers `systemctl --output=json` (systemd 244+) for clean
+// parsing and falls back to plain text on older systems. The choice is
+// probed once and cached on the agent so we don't pay the fork cost on
+// every list call.
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "os/exec"
+ "strings"
+ "time"
+
+ "github.com/serverkit/agent/internal/jobs"
+ "github.com/serverkit/agent/pkg/protocol"
+)
+
+// runSystemctlPrivileged is the sudo-aware variant of runSystemctl. It
+// preserves the existing 30-second timeout for read operations; long
+// operations (start/stop/restart/daemon-reload) override via timeout
+// param.
+func (a *Agent) runSystemctlPrivileged(ctx context.Context, timeout time.Duration, args ...string) (string, error) {
+ cctx, cancel := context.WithTimeout(ctx, timeout)
+ defer cancel()
+ cmd, err := sudoCommandContext(cctx, a.sudoMode, "systemctl", args...)
+ if err != nil {
+ return "", err
+ }
+ out, err := cmd.CombinedOutput()
+ return strings.TrimSpace(string(out)), err
+}
+
+// ───── systemd:daemon_reload ──────────────────────────────────────
+
+func (a *Agent) handleSystemdDaemonReload(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ if err := systemctlAvailable(); err != nil {
+ return nil, err
+ }
+ out, err := a.runSystemctlPrivileged(ctx, 5*time.Minute, "daemon-reload")
+ if err != nil {
+ if classifySudoError(out) {
+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)
+ }
+ return nil, fmt.Errorf("systemctl daemon-reload: %w (%s)", err, out)
+ }
+ return map[string]interface{}{
+ "action": "daemon_reloaded",
+ "output": out,
+ }, nil
+}
+
+// ───── systemd:list_units ─────────────────────────────────────────
+
+// systemctlUnit is the canonical row shape returned by list_units
+// regardless of whether we got JSON or plain text from systemctl.
+type systemctlUnit struct {
+ Unit string `json:"unit"`
+ Load string `json:"load,omitempty"`
+ Active string `json:"active,omitempty"`
+ Sub string `json:"sub,omitempty"`
+ Description string `json:"description,omitempty"`
+}
+
+func (a *Agent) handleSystemdListUnits(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ if err := systemctlAvailable(); err != nil {
+ return nil, err
+ }
+ var p struct {
+ State string `json:"state"` // optional filter: failed, active, inactive…
+ Type string `json:"type"` // unit type: service (default), socket, timer…
+ }
+ _ = json.Unmarshal(params, &p)
+ if p.Type == "" {
+ p.Type = "service"
+ }
+ if err := validateUnitName(p.Type); err != nil {
+ return nil, fmt.Errorf("type: %w", err)
+ }
+ if p.State != "" {
+ if err := validateUnitName(p.State); err != nil {
+ return nil, fmt.Errorf("state: %w", err)
+ }
+ }
+
+ args := []string{"list-units", "--all", "--no-legend", "--no-pager", "--type=" + p.Type}
+ if p.State != "" {
+ args = append(args, "--state="+p.State)
+ }
+
+ useJSON := a.detectSystemctlJSON(ctx)
+ if useJSON {
+ jsonArgs := append(append([]string{}, args...), "--output=json")
+ out, err := a.runSystemctlPrivileged(ctx, 30*time.Second, jsonArgs...)
+ if err == nil {
+ var rows []map[string]interface{}
+ if jerr := json.Unmarshal([]byte(out), &rows); jerr == nil {
+ units := make([]systemctlUnit, 0, len(rows))
+ for _, r := range rows {
+ u := systemctlUnit{}
+ if v, ok := r["unit"].(string); ok {
+ u.Unit = v
+ }
+ if v, ok := r["load"].(string); ok {
+ u.Load = v
+ }
+ if v, ok := r["active"].(string); ok {
+ u.Active = v
+ }
+ if v, ok := r["sub"].(string); ok {
+ u.Sub = v
+ }
+ if v, ok := r["description"].(string); ok {
+ u.Description = v
+ }
+ units = append(units, u)
+ }
+ return map[string]interface{}{"units": units, "format": "json"}, nil
+ }
+ }
+ // JSON failed (older systemd, malformed output) — fall through
+ // to plain text and remember the choice.
+ a.capMu.Lock()
+ a.capabilities.SystemdJSON = false
+ a.systemdJSON = false
+ a.capMu.Unlock()
+ }
+
+ // Plain text fallback. Columns: UNIT LOAD ACTIVE SUB DESCRIPTION.
+ out, err := a.runSystemctlPrivileged(ctx, 30*time.Second, args...)
+ if err != nil {
+ if classifySudoError(out) {
+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)
+ }
+ return nil, fmt.Errorf("systemctl list-units: %w (%s)", err, truncate(out, 1024))
+ }
+ units := parsePlainListUnits(out)
+ return map[string]interface{}{"units": units, "format": "plain"}, nil
+}
+
+// detectSystemctlJSON probes once whether `systemctl --output=json` is
+// supported. Caches the result on the agent + advertises via the
+// capabilities payload so the panel can show an "older systemd" hint.
+func (a *Agent) detectSystemctlJSON(ctx context.Context) bool {
+ a.systemdJSONOnce.Do(func() {
+ cctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+ defer cancel()
+ err := exec.CommandContext(cctx, "systemctl", "list-units", "--no-legend", "--no-pager", "--output=json", "--type=service").Run()
+ ok := err == nil
+ a.capMu.Lock()
+ a.systemdJSON = ok
+ a.capabilities.SystemdJSON = ok
+ a.capMu.Unlock()
+ })
+ a.capMu.Lock()
+ defer a.capMu.Unlock()
+ return a.systemdJSON
+}
+
+func parsePlainListUnits(out string) []systemctlUnit {
+ units := []systemctlUnit{}
+ for _, line := range strings.Split(out, "\n") {
+ line = strings.TrimSpace(line)
+ if line == "" || strings.HasPrefix(line, "●") {
+ continue
+ }
+ fields := strings.Fields(line)
+ if len(fields) < 4 {
+ continue
+ }
+ u := systemctlUnit{
+ Unit: fields[0],
+ Load: fields[1],
+ Active: fields[2],
+ Sub: fields[3],
+ }
+ if len(fields) > 4 {
+ u.Description = strings.Join(fields[4:], " ")
+ }
+ units = append(units, u)
+ }
+ return units
+}
+
+// ───── systemd:logs (bounded fetch) ──────────────────────────────
+
+func (a *Agent) handleSystemdLogs(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ if err := systemctlAvailable(); err != nil {
+ return nil, err
+ }
+ var p struct {
+ Unit string `json:"unit"`
+ Lines int `json:"lines"`
+ }
+ if err := json.Unmarshal(params, &p); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ if err := validateUnitName(p.Unit); err != nil {
+ return nil, err
+ }
+ if p.Lines <= 0 {
+ p.Lines = 200
+ }
+ if p.Lines > 5000 {
+ p.Lines = 5000
+ }
+
+ if _, err := exec.LookPath("journalctl"); err != nil {
+ return nil, errors.New("journalctl not on PATH")
+ }
+
+ cctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+ defer cancel()
+ cmd, err := sudoCommandContext(cctx, a.sudoMode, "journalctl",
+ "-u", p.Unit, "--no-pager", "-n", fmt.Sprintf("%d", p.Lines), "-o", "json")
+ if err != nil {
+ return nil, err
+ }
+ out, err := cmd.CombinedOutput()
+ if err != nil {
+ if classifySudoError(string(out)) {
+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)
+ }
+ return nil, fmt.Errorf("journalctl -u %s: %w (%s)", p.Unit, err, truncate(string(out), 1024))
+ }
+
+ // journalctl -o json prints one JSON object per line. Parse each
+ // into a flat shape the panel can render directly.
+ type entry struct {
+ Time string `json:"time"`
+ Priority string `json:"priority"`
+ PID string `json:"pid"`
+ Message string `json:"message"`
+ }
+ var entries []entry
+ for _, line := range strings.Split(string(out), "\n") {
+ line = strings.TrimSpace(line)
+ if line == "" {
+ continue
+ }
+ var raw map[string]interface{}
+ if err := json.Unmarshal([]byte(line), &raw); err != nil {
+ continue
+ }
+ e := entry{
+ Time: stringField(raw, "__REALTIME_TIMESTAMP"),
+ Priority: stringField(raw, "PRIORITY"),
+ PID: stringField(raw, "_PID"),
+ Message: stringField(raw, "MESSAGE"),
+ }
+ entries = append(entries, e)
+ }
+ return map[string]interface{}{
+ "unit": p.Unit,
+ "lines": p.Lines,
+ "entries": entries,
+ }, nil
+}
+
+func stringField(m map[string]interface{}, k string) string {
+ v, ok := m[k]
+ if !ok {
+ return ""
+ }
+ switch t := v.(type) {
+ case string:
+ return t
+ case float64:
+ return fmt.Sprintf("%.0f", t)
+ default:
+ return fmt.Sprintf("%v", t)
+ }
+}
+
+// ───── systemd:logs_follow (streaming) ───────────────────────────
+
+// handleSystemdLogsFollow returns a job channel and starts streaming
+// `journalctl -fu <unit>` lines on it. The job ends when either the
+// caller unsubscribes (which we detect by closing job.Done) or a fixed
+// 1-hour cap elapses to prevent runaway logs.
+//
+// The pattern mirrors handlePackagesInstallAsync: hand back
+// {job_id, channel} immediately, work happens in a goroutine.
+func (a *Agent) handleSystemdLogsFollow(ctx context.Context, params json.RawMessage) (interface{}, error) {
+ if err := systemctlAvailable(); err != nil {
+ return nil, err
+ }
+ var p struct {
+ Unit string `json:"unit"`
+ }
+ if err := json.Unmarshal(params, &p); err != nil {
+ return nil, fmt.Errorf("invalid params: %w", err)
+ }
+ if err := validateUnitName(p.Unit); err != nil {
+ return nil, err
+ }
+ if _, err := exec.LookPath("journalctl"); err != nil {
+ return nil, errors.New("journalctl not on PATH")
+ }
+
+ job := a.jobs.New(500)
+ // The protocol channel format is documented but we override to use
+ // the job: namespace so the panel's existing job-channel
+ // infrastructure handles it. The systemd:<unit>:logs format is
+ // reserved for a future multi-subscriber broadcast variant.
+ _ = protocol.ChannelSystemdLogs
+ go a.runSystemdLogsFollowJob(job, p.Unit)
+ return map[string]interface{}{
+ "job_id": job.ID,
+ "channel": job.Channel,
+ "unit": p.Unit,
+ }, nil
+}
+
+func (a *Agent) runSystemdLogsFollowJob(job *jobs.Job, unit string) {
+ exit := 0
+ emitDone := func(errStr string) {
+ _ = job.Push(a.ws, jobs.Event{
+ Phase: jobs.PhaseDone,
+ ExitCode: &exit,
+ Error: errStr,
+ Extra: map[string]interface{}{"unit": unit},
+ })
+ }
+
+ // Cap any single follow at 1 hour. Panel can re-subscribe.
+ cctx, cancel := context.WithTimeout(context.Background(), 1*time.Hour)
+ defer cancel()
+ cmd, err := sudoCommandContext(cctx, a.sudoMode, "journalctl",
+ "-fu", unit, "--no-pager", "-o", "short-iso")
+ if err != nil {
+ exit = -1
+ emitDone(err.Error())
+ return
+ }
+ _ = job.Push(a.ws, jobs.Event{
+ Phase: jobs.PhaseStart,
+ Message: fmt.Sprintf("following journal for %s", unit),
+ })
+ if err := streamCmdOutput(cmd, job, a.ws); err != nil {
+ exit = -1
+ emitDone(err.Error())
+ return
+ }
+ if cerr := cmd.Wait(); cerr != nil {
+ exit = exitCodeOf(cerr)
+ // journalctl returns non-zero when killed by the deadline; that's
+ // a graceful end, not an error.
+ if cctx.Err() == context.DeadlineExceeded {
+ emitDone("")
+ return
+ }
+ emitDone(cerr.Error())
+ return
+ }
+ emitDone("")
+}
diff --git a/agent/internal/agent/workflow_handlers.go b/agent/internal/agent/workflow_handlers.go
index 1d0766e5..1857cf91 100644
--- a/agent/internal/agent/workflow_handlers.go
+++ b/agent/internal/agent/workflow_handlers.go
@@ -270,6 +270,12 @@ func (a *Agent) handleSystemdStatus(ctx context.Context, params json.RawMessage)
}, nil
}
+// systemdMutateTimeout is the per-action timeout for state-changing
+// systemctl calls (start/stop/restart/enable/disable). Cold service
+// starts (postgresql, mongodb) routinely take 30-90s, so the original
+// 30s ceiling was too tight; bump to 2 minutes.
+const systemdMutateTimeout = 2 * time.Minute
+
func (a *Agent) handleSystemdStart(ctx context.Context, params json.RawMessage) (interface{}, error) {
if err := systemctlAvailable(); err != nil {
return nil, err
@@ -278,7 +284,10 @@ func (a *Agent) handleSystemdStart(ctx context.Context, params json.RawMessage)
if err != nil {
return nil, err
}
- if out, err := runSystemctl(ctx, "start", unit); err != nil {
+ if out, err := a.runSystemctlPrivileged(ctx, systemdMutateTimeout, "start", unit); err != nil {
+ if classifySudoError(out) {
+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)
+ }
return nil, fmt.Errorf("systemctl start %s: %w (%s)", unit, err, out)
}
return map[string]interface{}{"unit": unit, "action": "started"}, nil
@@ -292,7 +301,10 @@ func (a *Agent) handleSystemdStop(ctx context.Context, params json.RawMessage) (
if err != nil {
return nil, err
}
- if out, err := runSystemctl(ctx, "stop", unit); err != nil {
+ if out, err := a.runSystemctlPrivileged(ctx, systemdMutateTimeout, "stop", unit); err != nil {
+ if classifySudoError(out) {
+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)
+ }
return nil, fmt.Errorf("systemctl stop %s: %w (%s)", unit, err, out)
}
return map[string]interface{}{"unit": unit, "action": "stopped"}, nil
@@ -306,7 +318,10 @@ func (a *Agent) handleSystemdRestart(ctx context.Context, params json.RawMessage
if err != nil {
return nil, err
}
- if out, err := runSystemctl(ctx, "restart", unit); err != nil {
+ if out, err := a.runSystemctlPrivileged(ctx, systemdMutateTimeout, "restart", unit); err != nil {
+ if classifySudoError(out) {
+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)
+ }
return nil, fmt.Errorf("systemctl restart %s: %w (%s)", unit, err, out)
}
return map[string]interface{}{"unit": unit, "action": "restarted"}, nil
@@ -320,7 +335,10 @@ func (a *Agent) handleSystemdEnable(ctx context.Context, params json.RawMessage)
if err != nil {
return nil, err
}
- if out, err := runSystemctl(ctx, "enable", unit); err != nil {
+ if out, err := a.runSystemctlPrivileged(ctx, systemdMutateTimeout, "enable", unit); err != nil {
+ if classifySudoError(out) {
+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)
+ }
return nil, fmt.Errorf("systemctl enable %s: %w (%s)", unit, err, out)
}
return map[string]interface{}{"unit": unit, "action": "enabled"}, nil
@@ -334,7 +352,10 @@ func (a *Agent) handleSystemdDisable(ctx context.Context, params json.RawMessage
if err != nil {
return nil, err
}
- if out, err := runSystemctl(ctx, "disable", unit); err != nil {
+ if out, err := a.runSystemctlPrivileged(ctx, systemdMutateTimeout, "disable", unit); err != nil {
+ if classifySudoError(out) {
+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)
+ }
return nil, fmt.Errorf("systemctl disable %s: %w (%s)", unit, err, out)
}
return map[string]interface{}{"unit": unit, "action": "disabled"}, nil
diff --git a/agent/internal/capabilities/capabilities.go b/agent/internal/capabilities/capabilities.go
index da527071..92232958 100644
--- a/agent/internal/capabilities/capabilities.go
+++ b/agent/internal/capabilities/capabilities.go
@@ -283,3 +283,14 @@ func hasOnPath(name string) bool {
}
var pathCache sync.Map
+
+// ClearPathCache empties the binary-on-PATH cache. Called by agent:
+// recapabilities so a binary that was installed since the last probe
+// (e.g. the user just ran apt install nginx) is detected fresh
+// instead of returning the stale "not found" result.
+func ClearPathCache() {
+ pathCache.Range(func(k, _ interface{}) bool {
+ pathCache.Delete(k)
+ return true
+ })
+}
diff --git a/agent/internal/docker/client.go b/agent/internal/docker/client.go
index a415798b..b546ecec 100644
--- a/agent/internal/docker/client.go
+++ b/agent/internal/docker/client.go
@@ -11,8 +11,10 @@ import (
"github.com/docker/docker/api/types"
containertypes "github.com/docker/docker/api/types/container"
"github.com/docker/docker/api/types/filters"
+ networktypes "github.com/docker/docker/api/types/network"
volumetypes "github.com/docker/docker/api/types/volume"
"github.com/docker/docker/client"
+ "github.com/docker/go-connections/nat"
"github.com/serverkit/agent/internal/config"
"github.com/serverkit/agent/internal/logger"
)
@@ -440,6 +442,239 @@ func (c *Client) Close() error {
return c.cli.Close()
}
+// ───── container:create / container:exec / image:build / network:create
+
+// ContainerCreateSpec is the curated input shape for CreateContainer.
+// We deliberately don't expose raw HostConfig — the panel sends the
+// fields a one-click template needs and we map them. Privileged /
+// CapAdd / Devices are intentionally absent in v1; if a user needs
+// them they should run `docker create` directly.
+type ContainerCreateSpec struct {
+ Image string `json:"image"`
+ Name string `json:"name,omitempty"`
+ Command []string `json:"command,omitempty"`
+ Env []string `json:"env,omitempty"` // KEY=VAL
+ Labels map[string]string `json:"labels,omitempty"`
+ RestartPolicy string `json:"restart_policy,omitempty"` // no, on-failure, always, unless-stopped
+ Network string `json:"network,omitempty"`
+ Ports []ContainerPort `json:"ports,omitempty"`
+ Volumes []ContainerMount `json:"volumes,omitempty"`
+ WorkingDir string `json:"working_dir,omitempty"`
+}
+
+type ContainerPort struct {
+ Host uint16 `json:"host"`
+ Container uint16 `json:"container"`
+ Proto string `json:"proto,omitempty"` // "tcp" (default) or "udp"
+}
+
+type ContainerMount struct {
+ Source string `json:"src"`
+ Target string `json:"dst"`
+ Mode string `json:"mode,omitempty"` // "ro" or "" for rw
+}
+
+// CreateContainer wires a curated spec to the Docker SDK's
+// ContainerCreate. Returns the new container ID.
+func (c *Client) CreateContainer(ctx context.Context, spec ContainerCreateSpec) (string, error) {
+ if strings.TrimSpace(spec.Image) == "" {
+ return "", fmt.Errorf("image is required")
+ }
+
+ exposed := nat.PortSet{}
+ bindings := nat.PortMap{}
+ for _, p := range spec.Ports {
+ proto := p.Proto
+ if proto == "" {
+ proto = "tcp"
+ }
+ port, err := nat.NewPort(proto, fmt.Sprintf("%d", p.Container))
+ if err != nil {
+ return "", fmt.Errorf("invalid port %d/%s: %w", p.Container, proto, err)
+ }
+ exposed[port] = struct{}{}
+ bindings[port] = []nat.PortBinding{{HostIP: "0.0.0.0", HostPort: fmt.Sprintf("%d", p.Host)}}
+ }
+
+ binds := make([]string, 0, len(spec.Volumes))
+ for _, v := range spec.Volumes {
+ bind := v.Source + ":" + v.Target
+ if v.Mode != "" {
+ bind += ":" + v.Mode
+ }
+ binds = append(binds, bind)
+ }
+
+ cfg := &containertypes.Config{
+ Image: spec.Image,
+ Cmd: spec.Command,
+ Env: spec.Env,
+ Labels: spec.Labels,
+ WorkingDir: spec.WorkingDir,
+ ExposedPorts: exposed,
+ }
+ hostCfg := &containertypes.HostConfig{
+ PortBindings: bindings,
+ Binds: binds,
+ RestartPolicy: containertypes.RestartPolicy{
+ Name: spec.RestartPolicy,
+ },
+ }
+ var netCfg *networktypes.NetworkingConfig
+ if spec.Network != "" {
+ netCfg = &networktypes.NetworkingConfig{
+ EndpointsConfig: map[string]*networktypes.EndpointSettings{
+ spec.Network: {},
+ },
+ }
+ }
+ resp, err := c.cli.ContainerCreate(ctx, cfg, hostCfg, netCfg, nil, spec.Name)
+ if err != nil {
+ return "", err
+ }
+ return resp.ID, nil
+}
+
+// ContainerExecResult is the bounded result of an exec call.
+type ContainerExecResult struct {
+ Stdout string `json:"stdout"`
+ Stderr string `json:"stderr"`
+ ExitCode int `json:"exit_code"`
+}
+
+// ExecContainer runs a command inside a running container, captures
+// stdout/stderr (capped to outputCap bytes), and returns the exit code.
+// User and WorkingDir are optional; pass an empty string to inherit.
+func (c *Client) ExecContainer(ctx context.Context, id string, cmd []string, user, workingDir string, outputCap int) (ContainerExecResult, error) {
+ if outputCap <= 0 {
+ outputCap = 1024 * 1024 // 1MB default
+ }
+ createResp, err := c.cli.ContainerExecCreate(ctx, id, types.ExecConfig{
+ Cmd: cmd,
+ AttachStdout: true,
+ AttachStderr: true,
+ User: user,
+ WorkingDir: workingDir,
+ })
+ if err != nil {
+ return ContainerExecResult{}, err
+ }
+ hijack, err := c.cli.ContainerExecAttach(ctx, createResp.ID, types.ExecStartCheck{})
+ if err != nil {
+ return ContainerExecResult{}, err
+ }
+ defer hijack.Close()
+
+ // Read multiplexed stream: docker frames stdout/stderr together
+ // with an 8-byte header. stdcopy.StdCopy demultiplexes, but to
+ // avoid an extra import we use a bounded ReadAll and ship the raw
+ // stream — the panel only needs the combined output anyway.
+ buf := &boundedBuffer{cap: outputCap}
+ _, _ = io.Copy(buf, hijack.Reader)
+
+ insp, err := c.cli.ContainerExecInspect(ctx, createResp.ID)
+ if err != nil {
+ return ContainerExecResult{}, err
+ }
+ return ContainerExecResult{
+ Stdout: buf.String(),
+ ExitCode: insp.ExitCode,
+ }, nil
+}
+
+// boundedBuffer is a tiny io.Writer that drops bytes past a cap. Used
+// instead of bytes.Buffer to keep exec output from blowing memory on a
+// chatty command like `find /`.
+type boundedBuffer struct {
+ cap int
+ data []byte
+}
+
+func (b *boundedBuffer) Write(p []byte) (int, error) {
+ remaining := b.cap - len(b.data)
+ if remaining <= 0 {
+ return len(p), nil
+ }
+ if len(p) > remaining {
+ b.data = append(b.data, p[:remaining]...)
+ return len(p), nil
+ }
+ b.data = append(b.data, p...)
+ return len(p), nil
+}
+
+func (b *boundedBuffer) String() string { return string(b.data) }
+
+// ImageBuildSpec carries the curated input for BuildImage.
+type ImageBuildSpec struct {
+ ContextPath string `json:"context_path"`
+ Dockerfile string `json:"dockerfile,omitempty"`
+ Tag string `json:"tag"`
+ BuildArgs map[string]string `json:"build_args,omitempty"`
+ NoCache bool `json:"no_cache,omitempty"`
+ Pull bool `json:"pull,omitempty"`
+}
+
+// BuildImageCmd builds the *exec.Cmd for a `docker build` invocation
+// based on spec. The caller streams stdout/stderr (we use the same
+// jobs streaming helper as packages). Returning a Cmd rather than a
+// reader keeps this file from importing the docker SDK's archive
+// package, which pulls in containerd/moby deps that aren't in our
+// go.mod.
+func (c *Client) BuildImageCmd(ctx context.Context, spec ImageBuildSpec) (*exec.Cmd, error) {
+ if strings.TrimSpace(spec.ContextPath) == "" {
+ return nil, fmt.Errorf("context_path is required")
+ }
+ if strings.TrimSpace(spec.Tag) == "" {
+ return nil, fmt.Errorf("tag is required")
+ }
+ args := []string{"build", "-t", spec.Tag}
+ if spec.Dockerfile != "" {
+ args = append(args, "-f", spec.Dockerfile)
+ }
+ for k, v := range spec.BuildArgs {
+ args = append(args, "--build-arg", k+"="+v)
+ }
+ if spec.NoCache {
+ args = append(args, "--no-cache")
+ }
+ if spec.Pull {
+ args = append(args, "--pull")
+ }
+ args = append(args, spec.ContextPath)
+ return exec.CommandContext(ctx, "docker", args...), nil
+}
+
+// NetworkCreateSpec carries curated input for CreateNetwork.
+type NetworkCreateSpec struct {
+ Name string `json:"name"`
+ Driver string `json:"driver,omitempty"` // bridge (default), overlay, host
+ Internal bool `json:"internal,omitempty"`
+ Attachable bool `json:"attachable,omitempty"`
+ Labels map[string]string `json:"labels,omitempty"`
+}
+
+// CreateNetwork creates a Docker network and returns its ID.
+func (c *Client) CreateNetwork(ctx context.Context, spec NetworkCreateSpec) (string, error) {
+ if strings.TrimSpace(spec.Name) == "" {
+ return "", fmt.Errorf("name is required")
+ }
+ driver := spec.Driver
+ if driver == "" {
+ driver = "bridge"
+ }
+ resp, err := c.cli.NetworkCreate(ctx, spec.Name, types.NetworkCreate{
+ Driver: driver,
+ Internal: spec.Internal,
+ Attachable: spec.Attachable,
+ Labels: spec.Labels,
+ })
+ if err != nil {
+ return "", err
+ }
+ return resp.ID, nil
+}
+
// calculateCPUPercent calculates CPU usage percentage
func calculateCPUPercent(stats *types.StatsJSON) float64 {
cpuDelta := float64(stats.CPUStats.CPUUsage.TotalUsage - stats.PreCPUStats.CPUUsage.TotalUsage)
diff --git a/agent/internal/jobs/jobs.go b/agent/internal/jobs/jobs.go
new file mode 100644
index 00000000..0614ee35
--- /dev/null
+++ b/agent/internal/jobs/jobs.go
@@ -0,0 +1,196 @@
+// Package jobs tracks long-running operations (package installs, image
+// builds, pyenv installs) so the panel can subscribe to a streaming
+// channel and receive progress events as they happen, plus a replay of
+// recent events when subscribing mid-flight.
+//
+// A Job is created when a handler kicks off async work (e.g.
+// packages:install) and returns {job_id, channel} to the caller. The
+// handler then emits Event values via Job.Push, which:
+// - sends the event to the agent's stream transport (so any active
+// subscriber sees it live), AND
+// - records the event in a bounded ring buffer (so a late subscriber
+// can be caught up via Replay).
+//
+// The package is small on purpose — no goroutines, no timers, no I/O.
+// Callers own concurrency. The only synchronization is a mutex around
+// the registry map and per-job buffer mutex.
+package jobs
+
+import (
+ "crypto/rand"
+ "encoding/hex"
+ "fmt"
+ "sync"
+ "time"
+)
+
+// newID returns a 16-byte hex string suitable as a job identifier.
+// Falls back to a timestamp if /dev/urandom is unavailable, matching
+// the agent's auth.GenerateNonce style without taking a dep on it.
+func newID() string {
+ b := make([]byte, 16)
+ if _, err := rand.Read(b); err != nil {
+ return fmt.Sprintf("%d-%d", time.Now().UnixNano(), time.Now().UnixMilli())
+ }
+ return hex.EncodeToString(b)
+}
+
+// Phase enumerates lifecycle phases emitted by streaming jobs. The
+// panel uses these to drive its progress UI.
+const (
+ PhaseStart = "start"
+ PhaseLog = "log"
+ PhaseStatus = "status"
+ PhaseDone = "done"
+)
+
+// Event is the wire shape pushed onto a job's channel. Fields are kept
+// minimal and JSON-tagged so the panel can render terminal-style output
+// without per-handler parsers. Free-form Extra is for handlers that
+// want to attach structured data (e.g. installed package list) to the
+// final event.
+type Event struct {
+ Phase string `json:"phase"`
+ Lines []string `json:"lines,omitempty"`
+ Message string `json:"message,omitempty"`
+ Percent *int `json:"percent,omitempty"`
+ ExitCode *int `json:"exit_code,omitempty"`
+ Error string `json:"error,omitempty"`
+ Extra map[string]interface{} `json:"extra,omitempty"`
+}
+
+// Job is one in-flight long-running operation. It owns a ring buffer
+// of recent events so late subscribers can replay missed history.
+type Job struct {
+ ID string
+ Channel string
+
+ mu sync.Mutex
+ events []Event // ring buffer
+ cap int
+ head int // index of the next slot to write
+ full bool // whether we've wrapped past cap
+
+ doneOnce sync.Once
+ done chan struct{}
+}
+
+// Streamer is the slice of the agent transport that jobs need. Wraps
+// SendStream so handlers don't have to import the transport package
+// directly.
+type Streamer interface {
+ SendStream(channel string, data interface{}) error
+}
+
+// Registry tracks active and recently-completed jobs by ID. The bounded
+// retention means a panel that subscribes to a job channel a few
+// seconds after it completed still sees the final event. After enough
+// new jobs land, the old job ages out and Replay returns nothing — at
+// which point the panel knows the job is gone and should show "no
+// progress available."
+type Registry struct {
+ mu sync.Mutex
+ jobs map[string]*Job
+ // keep the last MaxJobs jobs in memory so a brief subscribe-after-finish
+ // race still serves the final "done" event.
+ maxJobs int
+ order []string // FIFO of job IDs; trimmed when len > maxJobs
+}
+
+// NewRegistry returns a Registry retaining up to maxJobs jobs.
+func NewRegistry(maxJobs int) *Registry {
+ if maxJobs <= 0 {
+ maxJobs = 64
+ }
+ return &Registry{
+ jobs: make(map[string]*Job),
+ maxJobs: maxJobs,
+ }
+}
+
+// New creates and registers a new Job. bufferCap is the ring-buffer
+// size for replay (suggested 200).
+func (r *Registry) New(bufferCap int) *Job {
+ if bufferCap <= 0 {
+ bufferCap = 200
+ }
+ id := newID()
+ j := &Job{
+ ID: id,
+ Channel: "job:" + id,
+ events: make([]Event, bufferCap),
+ cap: bufferCap,
+ done: make(chan struct{}),
+ }
+ r.mu.Lock()
+ r.jobs[id] = j
+ r.order = append(r.order, id)
+ // Trim oldest jobs if we're over capacity.
+ for len(r.order) > r.maxJobs {
+ oldest := r.order[0]
+ r.order = r.order[1:]
+ delete(r.jobs, oldest)
+ }
+ r.mu.Unlock()
+ return j
+}
+
+// Get returns the job with the given ID, or nil if unknown.
+func (r *Registry) Get(id string) *Job {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ return r.jobs[id]
+}
+
+// LookupByChannel returns the job whose Channel matches the given
+// channel name (e.g. "job:<id>"), or nil. Used by Subscribe handlers
+// to decide whether to replay buffered events.
+func (r *Registry) LookupByChannel(channel string) *Job {
+ if len(channel) <= 4 || channel[:4] != "job:" {
+ return nil
+ }
+ return r.Get(channel[4:])
+}
+
+// Push records an event in the ring buffer and pushes it on the
+// transport's stream channel. Panic-safe: a nil streamer just records
+// the event, useful for tests.
+func (j *Job) Push(s Streamer, ev Event) error {
+ j.mu.Lock()
+ j.events[j.head] = ev
+ j.head = (j.head + 1) % j.cap
+ if j.head == 0 {
+ j.full = true
+ }
+ j.mu.Unlock()
+
+ if ev.Phase == PhaseDone {
+ j.doneOnce.Do(func() { close(j.done) })
+ }
+
+ if s == nil {
+ return nil
+ }
+ return s.SendStream(j.Channel, ev)
+}
+
+// Replay returns a copy of the buffered events in chronological order.
+// Used when a late subscriber wants to catch up.
+func (j *Job) Replay() []Event {
+ j.mu.Lock()
+ defer j.mu.Unlock()
+ if !j.full {
+ out := make([]Event, j.head)
+ copy(out, j.events[:j.head])
+ return out
+ }
+ // Ring is full: oldest is at head, newest is just before head.
+ out := make([]Event, 0, j.cap)
+ out = append(out, j.events[j.head:]...)
+ out = append(out, j.events[:j.head]...)
+ return out
+}
+
+// Done returns a channel closed when the job emits a final event with
+// Phase == PhaseDone. Useful for tests.
+func (j *Job) Done() <-chan struct{} { return j.done }
diff --git a/agent/internal/jobs/jobs_test.go b/agent/internal/jobs/jobs_test.go
new file mode 100644
index 00000000..aee2b9fb
--- /dev/null
+++ b/agent/internal/jobs/jobs_test.go
@@ -0,0 +1,114 @@
+package jobs
+
+import (
+ "strconv"
+ "sync"
+ "testing"
+)
+
+type recorder struct {
+ mu sync.Mutex
+ sent []Event
+}
+
+func (r *recorder) SendStream(channel string, data interface{}) error {
+ ev, _ := data.(Event)
+ r.mu.Lock()
+ r.sent = append(r.sent, ev)
+ r.mu.Unlock()
+ return nil
+}
+
+func TestRegistryNewAssignsUniqueChannel(t *testing.T) {
+ r := NewRegistry(8)
+ a := r.New(0)
+ b := r.New(0)
+ if a.ID == b.ID {
+ t.Fatal("expected unique IDs")
+ }
+ if a.Channel != "job:"+a.ID || b.Channel != "job:"+b.ID {
+ t.Fatalf("unexpected channels: %q %q", a.Channel, b.Channel)
+ }
+ if r.LookupByChannel(a.Channel) != a {
+ t.Fatal("LookupByChannel did not round-trip")
+ }
+ if r.LookupByChannel("metrics") != nil {
+ t.Fatal("non-job channel should return nil")
+ }
+}
+
+func TestPushAndReplayPreserveOrder(t *testing.T) {
+ r := NewRegistry(8)
+ j := r.New(4)
+ rec := &recorder{}
+
+ for i := 0; i < 3; i++ {
+ if err := j.Push(rec, Event{Phase: PhaseLog, Message: strconv.Itoa(i)}); err != nil {
+ t.Fatal(err)
+ }
+ }
+ got := j.Replay()
+ if len(got) != 3 {
+ t.Fatalf("want 3 events, got %d", len(got))
+ }
+ for i, ev := range got {
+ if ev.Message != strconv.Itoa(i) {
+ t.Fatalf("event %d out of order: %q", i, ev.Message)
+ }
+ }
+ if len(rec.sent) != 3 {
+ t.Fatalf("transport got %d events, want 3", len(rec.sent))
+ }
+}
+
+func TestRingBufferDropsOldest(t *testing.T) {
+ r := NewRegistry(8)
+ j := r.New(3)
+ rec := &recorder{}
+ for i := 0; i < 5; i++ {
+ _ = j.Push(rec, Event{Phase: PhaseLog, Message: strconv.Itoa(i)})
+ }
+ got := j.Replay()
+ if len(got) != 3 {
+ t.Fatalf("ring should hold 3 events, got %d", len(got))
+ }
+ // Oldest two events (0,1) should have been dropped; expect 2,3,4.
+ for i, ev := range got {
+ want := strconv.Itoa(i + 2)
+ if ev.Message != want {
+ t.Fatalf("ring order broken at %d: got %q want %q", i, ev.Message, want)
+ }
+ }
+}
+
+func TestDoneClosedOnTerminalEvent(t *testing.T) {
+ r := NewRegistry(8)
+ j := r.New(4)
+ select {
+ case <-j.Done():
+ t.Fatal("done before terminal event")
+ default:
+ }
+ exit := 0
+ _ = j.Push(nil, Event{Phase: PhaseDone, ExitCode: &exit})
+ select {
+ case <-j.Done():
+ default:
+ t.Fatal("done not closed after terminal event")
+ }
+ // Idempotent: second done event must not panic.
+ _ = j.Push(nil, Event{Phase: PhaseDone, ExitCode: &exit})
+}
+
+func TestRegistryEvictsOldestJobs(t *testing.T) {
+ r := NewRegistry(2)
+ j1 := r.New(0)
+ j2 := r.New(0)
+ j3 := r.New(0)
+ if r.Get(j1.ID) != nil {
+ t.Fatal("j1 should have been evicted")
+ }
+ if r.Get(j2.ID) == nil || r.Get(j3.ID) == nil {
+ t.Fatal("j2/j3 should still be present")
+ }
+}
diff --git a/agent/pkg/protocol/messages.go b/agent/pkg/protocol/messages.go
index 4931b7dc..118c791d 100644
--- a/agent/pkg/protocol/messages.go
+++ b/agent/pkg/protocol/messages.go
@@ -179,6 +179,25 @@ type CapabilitiesMessage struct {
// panel's file manager can render the available browse roots without
// guessing. Empty/missing => the panel must hide remote file features.
AllowedPaths []string `json:"allowed_paths,omitempty"`
+ // Sudo describes how the agent escalates privileges for handlers
+ // that need root (systemd, packages). Values: "root" (already root),
+ // "passwordless" (sudo -n works), "unavailable" (no escalation —
+ // privileged handlers will fail). Empty/missing means the panel
+ // should treat it as "unavailable" for safety.
+ Sudo string `json:"sudo,omitempty"`
+ // RuntimeManagers reports which version manager (if any) is
+ // installed for each runtime, e.g. {"python": "pyenv"} on Linux or
+ // {"python": "pyenv-win"} on Windows. Empty/missing key means no
+ // manager installed; the panel can offer the bootstrap action.
+ RuntimeManagers map[string]string `json:"runtime_managers,omitempty"`
+ // SystemdJSON indicates whether `systemctl --output=json` is
+ // supported (systemd >= 244). When false, list_units falls back to
+ // parsing the plain --no-legend table.
+ SystemdJSON bool `json:"systemd_json,omitempty"`
+ // ProbedAt is the unix milliseconds timestamp when the capabilities
+ // payload was computed. Lets the panel distinguish a fresh re-probe
+ // from a cached set replayed on reconnect.
+ ProbedAt int64 `json:"probed_at,omitempty"`
}
// SystemInfo contains detailed system information
@@ -244,18 +263,50 @@ const (
// Linux-only; the agent picks the right manager (apt/dnf/apk/…)
// based on what's on PATH. Calls are idempotent — installing an
// already-installed package is a no-op success.
+ //
+ // Install/Upgrade are long-running and stream progress on the
+ // returned job channel ("job:<id>") rather than blocking — the
+ // command result returns {job_id, channel} immediately.
ActionPackagesInstall = "packages:install"
ActionPackagesRemove = "packages:remove"
ActionPackagesListInstalled = "packages:list_installed"
+ ActionPackagesUpdateCache = "packages:update_cache"
+ // ActionPackagesInstallAsync is the streaming variant of
+ // ActionPackagesInstall: takes names[] (and/or a single name),
+ // returns {job_id, channel} immediately, and emits per-line install
+ // progress on the channel. Use this for the Packages tab UI; the
+ // synchronous variant is retained for the workflow engine's
+ // agent_command nodes which expect a structured result.
+ ActionPackagesInstallAsync = "packages:install_async"
+ ActionPackagesUpgrade = "packages:upgrade"
+ ActionPackagesSearch = "packages:search"
+ ActionPackagesInfo = "packages:info"
// Systemd unit actions. Linux-only and require systemd as PID 1
// (the capability probe already gates this).
- ActionSystemdStatus = "systemd:status"
- ActionSystemdStart = "systemd:start"
- ActionSystemdStop = "systemd:stop"
- ActionSystemdRestart = "systemd:restart"
- ActionSystemdEnable = "systemd:enable"
- ActionSystemdDisable = "systemd:disable"
+ ActionSystemdStatus = "systemd:status"
+ ActionSystemdStart = "systemd:start"
+ ActionSystemdStop = "systemd:stop"
+ ActionSystemdRestart = "systemd:restart"
+ ActionSystemdEnable = "systemd:enable"
+ ActionSystemdDisable = "systemd:disable"
+ ActionSystemdDaemonReload = "systemd:daemon_reload"
+ ActionSystemdListUnits = "systemd:list_units"
+ ActionSystemdLogs = "systemd:logs"
+ ActionSystemdLogsFollow = "systemd:logs_follow"
+
+ // Runtime version managers (Phase 5). Currently scoped to Python
+ // via pyenv on Linux and pyenv-win on Windows. Install/Bootstrap
+ // stream on a job channel like packages.
+ ActionRuntimesList = "runtimes:list"
+ ActionRuntimesPyenvBootstrap = "runtimes:pyenv:bootstrap"
+ ActionRuntimesPythonInstalled = "runtimes:python:installed"
+ ActionRuntimesPythonAvailable = "runtimes:python:available"
+ ActionRuntimesPythonInstall = "runtimes:python:install"
+ ActionRuntimesPythonUninstall = "runtimes:python:uninstall"
+ ActionRuntimesPythonSetGlobal = "runtimes:python:set_global"
+ ActionRuntimesPythonSetLocal = "runtimes:python:set_local"
+ ActionRuntimesPythonCurrent = "runtimes:python:current"
// Cron actions — manage entries in the agent host's user crontab.
// Linux-only; non-Linux agents return an "unsupported" error.
@@ -288,7 +339,8 @@ const (
ActionTerminalClose = "terminal:close"
// Agent actions
- ActionAgentUpdate = "agent:update"
+ ActionAgentUpdate = "agent:update"
+ ActionAgentRecapabilities = "agent:recapabilities"
// GUI / desktop capture actions. These are the agent-side primitives
// that panel extensions (e.g. serverkit-gui) call into. Implementation
@@ -305,6 +357,15 @@ const (
ChannelContainerLogs = "container:%s:logs"
ChannelContainerStats = "container:%s:stats"
ChannelTerminal = "terminal:%s"
+ // ChannelSystemdLogs streams journalctl -fu <unit> events. Lifecycle
+ // mirrors ChannelContainerLogs: subscribe starts the follow, unsubscribe
+ // (or socket close) stops it.
+ ChannelSystemdLogs = "systemd:%s:logs"
+ // ChannelJob is used for long-running operations (package install,
+ // image build, pyenv install) that return {job_id, channel} from
+ // their command result and stream progress events on the channel.
+ // Late subscribers receive a replay of the last N buffered events.
+ ChannelJob = "job:%s"
)
// CredentialUpdateMessage is sent by server to rotate credentials
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.py
index 2b0c3a17..d1c2db9f 100644
--- a/backend/app/api/servers.py
+++ b/backend/app/api/servers.py
@@ -2298,6 +2298,184 @@ def remote_cloudflared_delete(server_id, tunnel_ref):
return _agent_result(result)
+# ==================== Remote Capability Refresh ====================
+#
+# Lets the panel ask the agent to re-run its capability probe on
+# demand — useful after the user installs a runtime, sudoers entry,
+# or new package manager and wants new tabs to light up without an
+# agent service restart. The agent's response is the freshly merged
+# capabilities map; the agent additionally pushes via the persistent
+# Capabilities message so all panel listeners stay in sync.
+
+@servers_bp.route('/<server_id>/refresh-capabilities', methods=['POST'])
+@jwt_required()
+def remote_refresh_capabilities(server_id):
+ user_id = get_jwt_identity()
+ result = agent_registry.send_command(
+ server_id=server_id, action='agent:recapabilities',
+ params={}, user_id=user_id, timeout=20.0,
+ )
+ return _agent_result(result)
+
+
+# ==================== Remote Packages ====================
+#
+# Exposes the agent's packages:* surface for the Packages tab.
+# Long-running operations (install/upgrade) return {job_id, channel};
+# the frontend subscribes to Socket.IO room
+# server_<id>_<channel> for live progress events.
+
+from app.services.remote_packages_service import RemotePackagesService
+
+
+@servers_bp.route('/<server_id>/packages', methods=['GET'])
+@jwt_required()
+def remote_packages_list(server_id):
+ user_id = get_jwt_identity()
+ result = RemotePackagesService.list_installed(server_id, user_id=user_id)
+ return _agent_result(result)
+
+
+@servers_bp.route('/<server_id>/packages/search', methods=['GET'])
+@jwt_required()
+def remote_packages_search(server_id):
+ user_id = get_jwt_identity()
+ query = (request.args.get('q') or '').strip()
+ if not query:
+ return jsonify({'error': 'q is required'}), 400
+ try:
+ limit = int(request.args.get('limit', 100))
+ except (TypeError, ValueError):
+ limit = 100
+ result = RemotePackagesService.search(server_id, query, limit=limit, user_id=user_id)
+ return _agent_result(result)
+
+
+@servers_bp.route('/<server_id>/packages/info/<name>', methods=['GET'])
+@jwt_required()
+def remote_packages_info(server_id, name):
+ user_id = get_jwt_identity()
+ result = RemotePackagesService.info(server_id, name, user_id=user_id)
+ return _agent_result(result)
+
+
+@servers_bp.route('/<server_id>/packages/update-cache', methods=['POST'])
+@jwt_required()
+@developer_required
+def remote_packages_update_cache(server_id):
+ user_id = get_jwt_identity()
+ result = RemotePackagesService.update_cache(server_id, user_id=user_id)
+ return _agent_result(result)
+
+
+@servers_bp.route('/<server_id>/packages/install', methods=['POST'])
+@jwt_required()
+@developer_required
+def remote_packages_install(server_id):
+ """Streaming install. Body: {names: ['nginx', 'redis-server']}.
+ Returns {job_id, channel} immediately; the panel subscribes to the
+ matching Socket.IO room for live install output."""
+ user_id = get_jwt_identity()
+ data = request.get_json(silent=True) or {}
+ names = data.get('names') or []
+ if isinstance(names, str):
+ names = [names]
+ if not names:
+ return jsonify({'error': 'names is required'}), 400
+ result = RemotePackagesService.install_async(server_id, names, user_id=user_id)
+ return _agent_result(result)
+
+
+@servers_bp.route('/<server_id>/packages/remove', methods=['POST'])
+@jwt_required()
+@developer_required
+def remote_packages_remove(server_id):
+ user_id = get_jwt_identity()
+ data = request.get_json(silent=True) or {}
+ name = (data.get('name') or '').strip()
+ if not name:
+ return jsonify({'error': 'name is required'}), 400
+ result = RemotePackagesService.remove(server_id, name, user_id=user_id)
+ return _agent_result(result)
+
+
+@servers_bp.route('/<server_id>/packages/upgrade', methods=['POST'])
+@jwt_required()
+@developer_required
+def remote_packages_upgrade(server_id):
+ """Streaming upgrade. Body: {all: bool, names?: [...]}. Returns
+ {job_id, channel}."""
+ user_id = get_jwt_identity()
+ data = request.get_json(silent=True) or {}
+ names = data.get('names') or []
+ all_pkgs = bool(data.get('all', False))
+ if not all_pkgs and not names:
+ return jsonify({'error': 'either all=true or names=[...] required'}), 400
+ result = RemotePackagesService.upgrade(
+ server_id,
+ names=names if names else None,
+ all_packages=all_pkgs,
+ user_id=user_id,
+ )
+ return _agent_result(result)
+
+
+# ==================== Remote Services (systemd) ====================
+
+from app.services.remote_systemd_service import RemoteSystemdService
+
+
+@servers_bp.route('/<server_id>/services', methods=['GET'])
+@jwt_required()
+def remote_services_list(server_id):
+ user_id = get_jwt_identity()
+ state = request.args.get('state')
+ type_ = request.args.get('type', 'service')
+ result = RemoteSystemdService.list_units(server_id, state=state, type_=type_, user_id=user_id)
+ return _agent_result(result)
+
+
+# Static-suffix routes must come before the generic <unit>/<action>
+# route so Werkzeug picks the right matcher in registration order.
+
+@servers_bp.route('/<server_id>/services/daemon-reload', methods=['POST'])
+@jwt_required()
+@developer_required
+def remote_services_daemon_reload(server_id):
+ user_id = get_jwt_identity()
+ result = RemoteSystemdService.daemon_reload(server_id, user_id=user_id)
+ return _agent_result(result)
+
+
+@servers_bp.route('/<server_id>/services/<unit>/logs', methods=['GET'])
+@jwt_required()
+def remote_services_logs(server_id, unit):
+ user_id = get_jwt_identity()
+ try:
+ lines = int(request.args.get('lines', 200))
+ except (TypeError, ValueError):
+ lines = 200
+ result = RemoteSystemdService.logs(server_id, unit, lines=lines, user_id=user_id)
+ return _agent_result(result)
+
+
+@servers_bp.route('/<server_id>/services/<unit>', methods=['GET'])
+@jwt_required()
+def remote_services_status(server_id, unit):
+ user_id = get_jwt_identity()
+ result = RemoteSystemdService.status(server_id, unit, user_id=user_id)
+ return _agent_result(result)
+
+
+@servers_bp.route('/<server_id>/services/<unit>/<action>', methods=['POST'])
+@jwt_required()
+@developer_required
+def remote_services_control(server_id, unit, action):
+ user_id = get_jwt_identity()
+ result = RemoteSystemdService.control(server_id, unit, action, user_id=user_id)
+ return _agent_result(result)
+
+
# ==================== Remote File Operations ====================
#
# Endpoints under /servers/<id>/files/ proxy to the agent's file:*
diff --git a/backend/app/services/remote_packages_service.py b/backend/app/services/remote_packages_service.py
new file mode 100644
index 00000000..655ce7f7
--- /dev/null
+++ b/backend/app/services/remote_packages_service.py
@@ -0,0 +1,117 @@
+"""
+Remote Packages Service.
+
+Routes /api/v1/servers/<id>/packages/* requests through the agent
+registry to the host's package manager (apt/dnf/apk/pacman/zypper).
+
+Long-running operations (install_async, upgrade) return
+{job_id, channel} immediately and stream progress on the channel —
+the panel re-broadcasts those events to Socket.IO subscribers via
+agent_gateway.
+
+Short reads (list_installed, search, info, update_cache) are
+synchronous round-trips matching the cron service shape.
+"""
+
+from typing import Any, Dict, Iterable, List, Optional
+
+from app.services.agent_registry import agent_registry
+
+
+class RemotePackagesService:
+ """Thin dispatcher to the agent's packages:* handlers."""
+
+ @staticmethod
+ def _send(server_id: str, action: str, params: Optional[Dict[str, Any]] = None,
+ user_id: Optional[int] = None, timeout: float = 30.0) -> Dict[str, Any]:
+ return agent_registry.send_command(
+ server_id=server_id,
+ action=action,
+ params=params or {},
+ user_id=user_id,
+ timeout=timeout,
+ )
+
+ # ---- read paths -------------------------------------------------
+
+ @staticmethod
+ def list_installed(server_id: str, user_id: Optional[int] = None) -> Dict[str, Any]:
+ # The agent's list_installed shells `apt-get list --installed` /
+ # `dnf list installed` / etc., which can return ~250KB on a
+ # populated server. 30s budget is generous; usually subsecond.
+ return RemotePackagesService._send(
+ server_id, 'packages:list_installed', user_id=user_id, timeout=30.0,
+ )
+
+ @staticmethod
+ def search(server_id: str, query: str, limit: int = 100,
+ user_id: Optional[int] = None) -> Dict[str, Any]:
+ return RemotePackagesService._send(
+ server_id, 'packages:search',
+ params={'query': query, 'limit': limit},
+ user_id=user_id,
+ timeout=30.0,
+ )
+
+ @staticmethod
+ def info(server_id: str, name: str, user_id: Optional[int] = None) -> Dict[str, Any]:
+ return RemotePackagesService._send(
+ server_id, 'packages:info',
+ params={'name': name},
+ user_id=user_id,
+ timeout=30.0,
+ )
+
+ # ---- write paths ------------------------------------------------
+
+ @staticmethod
+ def update_cache(server_id: str, user_id: Optional[int] = None) -> Dict[str, Any]:
+ return RemotePackagesService._send(
+ server_id, 'packages:update_cache', user_id=user_id, timeout=180.0,
+ )
+
+ @staticmethod
+ def install(server_id: str, name: str, user_id: Optional[int] = None) -> Dict[str, Any]:
+ # Synchronous single-name install for callers that want a
+ # structured result (workflow_engine agent_command nodes).
+ return RemotePackagesService._send(
+ server_id, 'packages:install',
+ params={'name': name},
+ user_id=user_id,
+ timeout=15 * 60.0,
+ )
+
+ @staticmethod
+ def install_async(server_id: str, names: Iterable[str],
+ user_id: Optional[int] = None) -> Dict[str, Any]:
+ # Streaming variant: returns {job_id, channel}.
+ return RemotePackagesService._send(
+ server_id, 'packages:install_async',
+ params={'names': list(names)},
+ user_id=user_id,
+ timeout=10.0,
+ )
+
+ @staticmethod
+ def remove(server_id: str, name: str, user_id: Optional[int] = None) -> Dict[str, Any]:
+ return RemotePackagesService._send(
+ server_id, 'packages:remove',
+ params={'name': name},
+ user_id=user_id,
+ timeout=10 * 60.0,
+ )
+
+ @staticmethod
+ def upgrade(server_id: str, names: Optional[List[str]] = None, all_packages: bool = False,
+ user_id: Optional[int] = None) -> Dict[str, Any]:
+ params: Dict[str, Any] = {}
+ if all_packages:
+ params['all'] = True
+ if names:
+ params['names'] = list(names)
+ return RemotePackagesService._send(
+ server_id, 'packages:upgrade',
+ params=params,
+ user_id=user_id,
+ timeout=10.0,
+ )
diff --git a/backend/app/services/remote_systemd_service.py b/backend/app/services/remote_systemd_service.py
new file mode 100644
index 00000000..40091565
--- /dev/null
+++ b/backend/app/services/remote_systemd_service.py
@@ -0,0 +1,89 @@
+"""
+Remote Systemd Service.
+
+Wraps the agent's systemd:* handlers behind a simple Python surface so
+the API layer can call control_unit('nginx', 'restart') instead of
+threading actions and params manually.
+
+list_units returns canonical unit rows in either JSON or plain-parsed
+format — the agent flips automatically based on systemd version. The
+panel doesn't need to care which.
+"""
+
+from typing import Any, Dict, Optional
+
+from app.services.agent_registry import agent_registry
+
+
+_VALID_ACTIONS = {'start', 'stop', 'restart', 'enable', 'disable'}
+
+
+class RemoteSystemdService:
+ """Thin dispatcher to systemd:* on a remote agent."""
+
+ @staticmethod
+ def _send(server_id: str, action: str, params: Optional[Dict[str, Any]] = None,
+ user_id: Optional[int] = None, timeout: float = 30.0) -> Dict[str, Any]:
+ return agent_registry.send_command(
+ server_id=server_id,
+ action=action,
+ params=params or {},
+ user_id=user_id,
+ timeout=timeout,
+ )
+
+ @staticmethod
+ def list_units(server_id: str, state: Optional[str] = None, type_: str = 'service',
+ user_id: Optional[int] = None) -> Dict[str, Any]:
+ params: Dict[str, Any] = {'type': type_}
+ if state:
+ params['state'] = state
+ return RemoteSystemdService._send(
+ server_id, 'systemd:list_units', params=params,
+ user_id=user_id, timeout=30.0,
+ )
+
+ @staticmethod
+ def status(server_id: str, unit: str, user_id: Optional[int] = None) -> Dict[str, Any]:
+ return RemoteSystemdService._send(
+ server_id, 'systemd:status', params={'unit': unit},
+ user_id=user_id, timeout=15.0,
+ )
+
+ @staticmethod
+ def control(server_id: str, unit: str, action: str,
+ user_id: Optional[int] = None) -> Dict[str, Any]:
+ if action not in _VALID_ACTIONS:
+ return {'success': False, 'error': f'invalid action: {action}', 'code': 'INVALID_ACTION'}
+ # 2-minute timeout matches the agent's per-action ceiling for
+ # cold-starts on heavyweight units (postgresql etc.).
+ return RemoteSystemdService._send(
+ server_id, f'systemd:{action}', params={'unit': unit},
+ user_id=user_id, timeout=130.0,
+ )
+
+ @staticmethod
+ def daemon_reload(server_id: str, user_id: Optional[int] = None) -> Dict[str, Any]:
+ return RemoteSystemdService._send(
+ server_id, 'systemd:daemon_reload',
+ user_id=user_id, timeout=310.0,
+ )
+
+ @staticmethod
+ def logs(server_id: str, unit: str, lines: int = 200,
+ user_id: Optional[int] = None) -> Dict[str, Any]:
+ return RemoteSystemdService._send(
+ server_id, 'systemd:logs',
+ params={'unit': unit, 'lines': int(lines)},
+ user_id=user_id, timeout=30.0,
+ )
+
+ @staticmethod
+ def logs_follow(server_id: str, unit: str,
+ user_id: Optional[int] = None) -> Dict[str, Any]:
+ # Returns {job_id, channel}; the panel re-broadcasts on Socket.IO.
+ return RemoteSystemdService._send(
+ server_id, 'systemd:logs_follow',
+ params={'unit': unit},
+ user_id=user_id, timeout=10.0,
+ )