> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the Terminal in Your Dev Container

> Run commands directly inside your project's container

Your Hiveku dev container runs a full Linux shell. Open a terminal to install packages, run scripts, tail logs, and debug live — no separate local setup required.

## Open the Terminal

<Steps>
  <Step title="Open your project">
    From the dashboard, click into the project you want to work in.
  </Step>

  <Step title="Navigate to the Infrastructure Dashboard">
    Click **Settings > Infrastructure Dashboard** and find the container for the environment you're working in (production, staging, development).
  </Step>

  <Step title="Expand the container details">
    Click the container row to expand it. You'll see status, resource usage, and a **Open Terminal** button.
  </Step>

  <Step title="Click Open Terminal">
    A terminal panel opens in the dashboard. You can also use the terminal icon in the code editor toolbar as a shortcut.
  </Step>
</Steps>

## Terminal Status Indicator

Every container shows whether terminal access is supported:

| Status          | Meaning                                                     |
| --------------- | ----------------------------------------------------------- |
| **Yes** (green) | Terminal is supported on this container                     |
| **No** (red)    | Legacy container image — no terminal support                |
| **Checking**    | Hiveku is inspecting the container                          |
| **Unknown**     | Status couldn't be determined — try refreshing, or redeploy |

If you see **No**, redeploy the project. Your next deployment uses the latest container image, which supports terminal.

## Common Tasks

Once you're in the shell, you have a full userland. Some typical things you'll do:

### Add or update packages

```bash theme={null}
# Node / Next.js
npm install stripe
npm update

# Python
python -m pip install requests

# Go
go mod tidy
```

### Run scripts

```bash theme={null}
# Any script in package.json
npm run test
npm run lint

# Or run a file directly
node scripts/seed.js
python scripts/migrate.py
```

### Follow logs

```bash theme={null}
tail -f /var/log/app.log
```

### Inspect env vars

```bash theme={null}
# Shows what's actually injected into the container
cat .env
printenv | grep DATABASE
```

### Check the runtime

```bash theme={null}
node --version
python --version
whoami
uname -a
```

## Persistence

<Warning>
  Changes to the container filesystem **outside your project files** don't persist across restarts. If you install a package with `npm install foo` and it writes to `package.json`, that's fine — it persists. But installing something globally with `apt install` or writing to `/tmp` will vanish.
</Warning>

For reliable persistence, install packages through your project's dependency manifest:

* `package.json` for Node projects
* `requirements.txt` or `pyproject.toml` for Python
* `go.mod` for Go

When you run `npm install <package>`, the added dependency in `package.json` survives restarts. The `node_modules` directory is rebuilt from that manifest on every fresh container.

<Info>
  Files you edit in the terminal sync back to Hiveku's file system in real time. Your code editor reflects changes you make with `vim`, `nano`, or `sed` immediately — and vice versa.
</Info>

## Security

Terminals are scoped to your project and gated on your Hiveku auth token. Key guarantees:

* Only project collaborators with the right role can open a terminal
* Sessions are logged for audit purposes
* The container runs as a non-root user — `sudo` is intentionally unavailable

If you need elevated access or a custom base image, contact support with your use case.

## Verify the Terminal Works

<Steps>
  <Step title="Open the terminal">
    Use either path above.
  </Step>

  <Step title="Run a quick sanity check">
    Type `whoami && pwd && ls`. You should see the container user, the project working directory, and a listing of your project files.
  </Step>

  <Step title="Try installing a package">
    `npm install lodash` (or equivalent in your stack). The package is added and will persist across restarts because it's now in `package.json`.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Terminal not supported (legacy container)">
    Your project was deployed on an older container image. Redeploy the project from the Hosting page — the new deployment pulls a current image with terminal support.
  </Accordion>

  <Accordion title="Terminal disconnects mid-session">
    Usually a network hiccup or an idle timeout. Click **Reconnect** — your container state is preserved, you just need to re-establish the session. Long-running processes in the background (e.g., `tail -f`) are killed when the terminal disconnects — use `nohup` or `screen` alternatives aren't installed by default.
  </Accordion>

  <Accordion title="'command not found'">
    The tool isn't installed. For language-level tools (`npm`, `pip`, `go`), they're pre-installed for your stack. For system utilities, install what you need via your package manifest. `apt` may be available but changes won't persist — install at the project level instead.
  </Accordion>

  <Accordion title="Permission denied / no root">
    Expected — the terminal runs as a non-root user. You can't `sudo` and can't write to system directories. Write inside your project directory or `/tmp` (for the session).
  </Accordion>

  <Accordion title="Changes aren't showing in the code editor">
    Give it a second — sync is fast but not instant for large files. If a file you edited in the terminal still shows the old content in the editor, close and reopen the file.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="View Deployment & Runtime Logs" icon="scroll" href="/how-tos/view-logs">
    Debug what's happening in production
  </Card>

  <Card title="Environment Variables" icon="key" href="/how-tos/env-vars">
    Configure secrets and runtime config
  </Card>
</CardGroup>