---
title: 'Headless Mode'
sidebar_position: 310
description: How to run Gadgets without a client
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Instead of running Gadgets interactively, you can also install Gadget Instances on your server, so they keep running
even if you are no longer connected. This also ensures that Gadgets will be resumed after a node restart or - depending
on the environment - when nodes are added to your cluster.

:::tip
If you are deploying Inspektor Gadget with Helm, you can pre-configure Gadget Instances directly in your
`values.yaml` using the `config.gadgetConfigMaps` option. See [Pre-configuring Gadget Instances](./install-kubernetes.md#pre-configuring-gadget-instances) for details.
:::

## Creating Gadget Instances

To create a new Gadget Instance on your server / cluster, you can use the `run` command with the `--detach` option:

<Tabs groupId="env">
    <TabItem value="gadgetctl" label="gadgetctl">

```bash
$ gadgetctl run trace_exec:latest --detach
INFO[0001] installed on node "local" as "61c8fdd9b75e1aec3c242347f18cf854"
```
    </TabItem>
    <TabItem value="kubectl-gadget" label="kubectl-gadget">

```bash
$ kubectl gadget run trace_exec:latest --detach
INFO[0001] installed as "f0ff5614be1a0da655ea308e13ce6605"
ID           NAME                     TAGS                     GADGET
4f5ae12c54bd serene_tu                                         trace_open:latest
f0ff5614be1a brave_bartik                                      trace_exec:latest
```
    </TabItem>
</Tabs>

The command returns the ID of the newly installed Gadget Instance.

:::warning
When upgrading server versions, please make sure to also upgrade all existing Gadget Instances to avoid compatibility issues. For example in Kubernetes you should see following warning in the server logs:
```
$ kubectl logs -n gadget -l k8s-app=gadget
...
time="2025-09-26T07:50:38Z" level=warning msg="This gadget was built with ig v0.42.0 and it's being run with v0.44.1. Gadget could be incompatible"
time="2025-09-26T07:50:40Z" level=error msg="running gadget: starting operators: starting operator \"oci\": starting operator \"ebpf\": creating eBPF collection: program ig_trace_dns: load program: bad CO-RE relocation: invalid func unknown#195896080 (303 line(s) omitted)"
...
```
Please [delete](#deleting-a-gadget-instance) and re-create the Gadget Instance to resolve this.
:::

## Listing Gadget Instances

To list all existing Gadget Instances on the server, you can run:

<Tabs groupId="env">
    <TabItem value="gadgetctl" label="gadgetctl">

```bash
$ gadgetctl list
ID           NAME                     TAGS                     GADGET
4f5ae12c54bd serene_tu                                         trace_open:latest
61c8fdd9b75e brave_bartik                                      trace_exec:latest
```
    </TabItem>
    <TabItem value="kubectl-gadget" label="kubectl-gadget">

```bash
$ kubectl gadget list
ID           NAME                     TAGS                     GADGET
4f5ae12c54bd serene_tu                                         trace_open:latest
61c8fdd9b75e brave_bartik                                      trace_exec:latest
```
    </TabItem>
</Tabs>

## Attaching to a Gadget Instance

If you want to see the output of the Gadget Instance, you can attach to it using the (partial) ID or name:

<Tabs groupId="env">
    <TabItem value="gadgetctl" label="gadgetctl">

```bash
$ gadgetctl attach 61c8fdd9b75e
RUNTIME.CONTAINERNAME    COMM                 PID        TID PCOMM               PPID ARGS          ERR… USER          LOGINUSER    GROUP
magical_pike             bash              282432     282432 containerd-s…     282410 /bin/bash          root          uid:4294967… root
magical_pike             groups            282454     282454 bash              282453 /usr/bin/gro…      root          uid:4294967… root
magical_pike             dircolors         282456     282456 bash              282455 /usr/bin/dir…      root          uid:4294967… root

$ gadgetctl attach brave_bartik
RUNTIME.CONTAINERNAME    COMM                 PID        TID PCOMM               PPID ARGS          ERR… USER          LOGINUSER    GROUP
magical_pike             bash              282432     282432 containerd-s…     282410 /bin/bash          root          uid:4294967… root
magical_pike             groups            282454     282454 bash              282453 /usr/bin/gro…      root          uid:4294967… root
magical_pike             dircolors         282456     282456 bash              282455 /usr/bin/dir…      root          uid:4294967… root
```
    </TabItem>
    <TabItem value="kubectl-gadget" label="kubectl-gadget">

```bash
$ kubectl gadget attach 61c8fdd9b75e
K8S.NODE                           K8S.NAMESPACE                      K8S.PODNAME                       K8S.CONTAINERNAME                 COMM                    PID        TID        UID        GID  FD FNAME                               MODE              ERROR
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        kube-proxy             4653       4692          0          0  10 /dev/null                           ----------
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        kube-proxy             4653       4824          0          0   9 /dev/null                           ----------
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        iptables             102586     102586          0          0   0 /etc/ld.so.cache                    ----------        ENOENT
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        ip6tables            102587     102587          0          0   0 /etc/ld.so.cache                    ----------        ENOENT
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        iptables             102586     102586          0          0   0 /lib/aarch64-linux-gnu/tls/aarch64… ----------        ENOENT
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        ip6tables            102587     102587          0          0   0 /lib/aarch64-linux-gnu/tls/aarch64… ----------        ENOENT

$ kubectl gadget attach brave_bartik
K8S.NODE                           K8S.NAMESPACE                      K8S.PODNAME                       K8S.CONTAINERNAME                 COMM                    PID        TID        UID        GID  FD FNAME                               MODE              ERROR
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        kube-proxy             4653       4692          0          0  10 /dev/null                           ----------
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        kube-proxy             4653       4824          0          0   9 /dev/null                           ----------
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        iptables             102586     102586          0          0   0 /etc/ld.so.cache                    ----------        ENOENT
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        ip6tables            102587     102587          0          0   0 /etc/ld.so.cache                    ----------        ENOENT
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        iptables             102586     102586          0          0   0 /lib/aarch64-linux-gnu/tls/aarch64… ----------        ENOENT
minikube-docker                    kube-system                        kube-proxy-hr474                  kube-proxy                        ip6tables            102587     102587          0          0   0 /lib/aarch64-linux-gnu/tls/aarch64… ----------        ENOENT
```
    </TabItem>
</Tabs>

## Deleting a Gadget Instance

To delete one or more Gadget Instances, just provide the names or (partial) IDs to the `delete` command, like so:

<Tabs groupId="env">
    <TabItem value="gadgetctl" label="gadgetctl">

```bash
$ gadgetctl delete 4f 61
4f5ae12c54bd7c2058c0484ebd13dbc2
61c8fdd9b75e1aec3c242347f18cf854
```
    </TabItem>
    <TabItem value="kubectl-gadget" label="kubectl-gadget">

```bash
$ kubectl gadget delete 4f 61
4f5ae12c54bd7c2058c0484ebd13dbc2
61c8fdd9b75e1aec3c242347f18cf854
```
    </TabItem>
</Tabs>
