Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions .agents/skills/devsy/references/providers.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,14 @@ can change the default. To keep the default, run
without initializing it. Options given to add do not carry over to init.

To use the provider, find the installed name and run
`devsy provider init <configured-name>` with the required repeatable
`--option KEY=VALUE` values. Init does not change the default. Then check the
status and the default with `provider_list` before you create a workspace. If
the user asked only for installation, report that init is still needed.
`devsy provider init <configured-name>`. For sensitive options, use the
`DEVSY_PROVIDER_<PROVIDER_NAME>_<OPTION_NAME>` environment variable instead
of passing `--option KEY=VALUE` on the command line. Use an established
credential mechanism to supply the variable without exposing it in shell
history or logs. See [Safety and authority](safety.md). Init does not change
the default. Then check the status and the default with `provider_list` before
you create a workspace. If the user asked only for installation, report that
init is still needed.

After an MCP add, check the default and report any change. Do not turn a request
for one workspace into a default change.
Expand All @@ -39,7 +43,7 @@ later creates that omit a provider and does not move existing workspaces.
## Remove or recover

Deleting a provider changes shared configuration and does not repair a
workspace. Confirm the target and intent, and check dependent workspaces. The
delete fails if workspaces use the provider. Do not force-remove the provider or
delete its workspaces to get past that. When a provider fails, diagnose its
configuration, connectivity, or runtime. Do not delete or replace it.
workspace. It fails if workspaces use the provider. When a provider fails,
diagnose its configuration, connectivity, or runtime. Do not delete or replace
the provider or its dependent workspaces as an automatic repair. Delete or
replace only when the user explicitly authorizes the exact target and action.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,7 @@ When your provider is ready:
1. Add your provider to `community.yaml`.
2. Document it in `sites/docs-devsy-sh/content/docs/managing-providers/manage-providers.mdx`.

The docs and the UI then list your provider.
The Desktop provider wizard does not read `community.yaml`. Its additional provider list comes from `devsy-org` repositories whose names start with `devsy-provider-`.

## Desktop deep links

Expand Down
5 changes: 3 additions & 2 deletions hack/ci/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,9 @@ e2e group from `e2e.suites`.
- **Ginkgo spec**: add its label to `e2e.suites` and choose a `group`. Set only
the fields that differ from the group defaults, such as `runner`,
`test_timeout`, `install_kind`, `install_podman`, `requires_secret`, and
`host_setup`. List labels that another workflow runs in `e2e.ungated` with a
reason.
`host_setup`. List labels that PR CI must not select directly in
`e2e.ungated` with a reason. These include sub-labels exercised by gated
suites and labels run manually or by another workflow.

`go test ./hack/ci` fails when a Ginkgo label or Go test package has no tier, or
when the manifest names a label that no longer exists. New tests need no
Expand Down
15 changes: 0 additions & 15 deletions hack/ci/suites.yaml
Original file line number Diff line number Diff line change
@@ -1,18 +1,3 @@
# Test tier manifest for the PR workflow (.github/workflows/pr-ci.yml).
#
# This file is the single place that defines what tests exist, where they run
# and how they run. The workflow contains no per-suite conditions; it asks
# `hack/ci matrix` for its job matrices and `hack/ci unit|e2e|setup` for the
# behaviour. hack/ci/manifest_test.go fails when a Ginkgo label or a Go test
# package is not assigned to a tier here.
#
# To add a test:
# - Go unit test in an ordinary package: nothing to do, it is discovered.
# - Go test in a package under test/ or e2e/ that must run as a unit test:
# add the package to a `unit.steps` entry.
# - Ginkgo spec: add its label to `e2e.suites` (or to `e2e.ungated` with a
# reason when another workflow runs it).

unit:
# One job per runner; every runner executes the steps whose `os` matches.
runners:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Continuous Integration
sidebar_label: Continuous Integration
---

`devsy ci` builds a temporary devcontainer, runs a command in it, and deletes the workspace afterward. Use it to check that your `devcontainer.json` builds and your tests pass inside it.
`devsy ci` starts a devcontainer workspace and runs a command in it. It deletes a newly created workspace afterward unless you pass `--keep`, but never deletes a workspace that existed before the run. Use it to run tests inside the container and check the build of a newly created workspace.

## How it works

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ build/

- A missing or empty file uploads everything.
- An unreadable file or invalid pattern stops the upload with an error naming the file.
- The file filters only the workspace folder upload. Extra bind mounts, local Docker bind mounts, and image builds follow their own rules. After a Git clone, Devsy deletes the paths the file lists, matched literally. Devsy does not read `.gitignore` or `.dockerignore`.
- The file filters only the workspace folder upload. Extra bind mounts, local Docker bind mounts, and image builds follow their own rules. After a Git clone, Devsy deletes the paths the file lists, matched literally. A negated rule such as `!build/keep.txt` cannot restore a file deleted with `build/` after a Git clone. Devsy does not read `.gitignore` or `.dockerignore`.

## Inspect a workspace

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Normal completion removes forwarded credentials before Devsy writes config back.

### Connections and troubleshooting

After you change the option, close existing service connections and reconnect. Restart a browser IDE to replace its services connection, and restart any older browser tunnel after you opt in. Changing the option does not revoke tokens that running code already has.
After you change the option, close existing service connections and reconnect. A running browser tunnel keeps the GitHub CLI setting it started with, and restarting the browser IDE reuses that tunnel. After opting out, stop the older browser tunnel process and reconnect so `/github-credentials` requests no longer access its host GitHub accounts. Changing the option does not revoke tokens that running code already has.

The guest's shared credential port has one live services owner. SSH sessions carry their expected host and service identity, and a mismatched or older service falls back to local authentication. Browser terminals and external SSH clients carry no session data, so they use the first live services owner. If two hosts use the same guest user, end the first connection before you change the owner. A second browser connection does not change or revoke the first owner's access.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ After you edit the configuration, apply it without deleting the workspace:
devsy workspace up my-workspace --recreate
```

Devsy applies every change, including the Dockerfile, mounts, and features. It replaces the running container only if the rebuild succeeds. A failed build leaves the existing workspace running.
Devsy builds and validates the new image before stopping or replacing the existing container. If the build fails, the existing workspace stays in its previous state, whether running or stopped. A later failure can leave the old container stopped or removed, depending on the provider. Pass `--recovery` to start a recovery container with features and lifecycle commands disabled if the build fails.

<Callout type="warn" title="Recreating">
Anything outside volumes is lost. The project folder and other mounted paths stay.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,6 @@ A pod whose daemon uses an older lifecycle protocol must be replaced once. `devs
Set `shutdownAction` in `devcontainer.json`. It is not a provider option.

- `none` turns off the container timeout monitor. For machines, it also stops `agent.exec.shutdown` from running.
- Any other value turns on the container timeout monitor. For machines, `agent.exec.shutdown` runs when the timeout passes, if the command is set.
- Any other value allows the container timeout monitor to run when the effective timeout is positive. For machines, `agent.exec.shutdown` runs when the timeout passes, if the command is set.

When `shutdownAction` is unset, the default is `stopCompose` for Compose workspaces and `stopContainer` for all others. Apart from `none`, and apart from Kubernetes rejecting `stopCompose`, the value does not change what the container timeout does.
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_label: Stop or Delete a Workspace

## Stop a workspace

Stopping pauses a workspace so it stops using CPU and memory. Depending on the provider, Devsy stops the container or shuts down the VM it runs on. The data is kept.
Stopping pauses a workspace so it stops using CPU and memory. Depending on the provider, Devsy stops the container or shuts down the VM it runs on. Workspace data is kept unless the provider discards disk state on shutdown, as microsandbox does with `ephemeral` enabled.

In Devsy Desktop, open the workspace actions menu and choose **Stop**. From the CLI, run:

Expand All @@ -25,7 +25,7 @@ Stopping or deleting a workspace first cancels its running `devsy workspace up -

## Delete a workspace

Deleting removes the workspace and all data Devsy stores about it. Depending on the provider, Devsy removes the container or deletes the VM.
Deleting removes the workspace and its local workspace data. Depending on the provider, Devsy removes the container or deletes the VM. Build and lifecycle output in [setup history](../troubleshooting/setup-history.mdx) stays in the local store until retention prunes it.

In Devsy Desktop, open the workspace actions menu, choose **Delete**, and confirm. If the delete fails, the workspace detail page shows the error and links to the logs.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar_label: Workspace Snapshots
A snapshot saves a workspace at one point in time: the container filesystem (installed packages, config changes) and the contents of the bind-mounted volume, including uncommitted code. Devsy stores snapshots as OCI artifacts in a registry you control. Restore a snapshot later or use it to move a workspace to another provider.

<Callout title="Registry required">
Devsy pushes snapshots to an OCI registry and pulls them from it. It does not store them locally. You need push and pull access.
Devsy pushes snapshots to an OCI registry and pulls them from it when needed. Creating a snapshot also leaves the committed container image locally after the push, but the registry is still required for the snapshot manifest and volume. You need push and pull access.
</Callout>

## Limitations
Expand Down
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@

## Install VirtualBox

### Minimum machine requirements
### Recommended resources for this walkthrough

Minimum requirements from the [VirtualBox](https://www.virtualbox.org/wiki/End-user_documentation) and
[Ubuntu Desktop](https://ubuntu.com/download/desktop) documentation:
For this walkthrough with [VirtualBox](https://www.virtualbox.org/wiki/End-user_documentation) and [Ubuntu Desktop](https://ubuntu.com/download/desktop), use these resource recommendations. They are not vendor minimum requirements.

| Item | Minimum requirement|
| Item | Recommendation |
|---|---|
| CPU | dual core CPU |
| RAM | 16GB (the walkthrough below allocates 8GB to the guest VM, so the host needs headroom on top of that) |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -154,10 +154,10 @@ ls ~/.kube
cache completion.bash.inc config
```

The `config` file in `~/.kube` is the kubeconfig for the Kubernetes provider. Set the kubeconfig path in the provider to:
The `config` file in `~/.kube` is the kubeconfig for the Kubernetes provider. Print its absolute path and use the output when configuring the provider:

```
/home/dev/.kube/config
```sh
echo ~/.kube/config
```

In production, give the kubeconfig a specific context, namespace, and user. Install kubectl on the machine where the Devsy client runs, because the Kubernetes provider runs kubectl with the local kubeconfig to reach a remote cluster.
Expand Down Expand Up @@ -191,7 +191,7 @@ Go to **Providers** > **+ Add** and select the Kubernetes provider.
|---|---|
| Kubernetes Namespace | default |
| Disk Size | 1Gi |
| Kubernetes Config | /home/dev/.kube/config |
| Kubernetes Config | The absolute path printed by `echo ~/.kube/config` |

Select **Add Provider**

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ devsy workspace ssh my-workspace

### Socket not found or permission denied

Devsy cannot reach the Podman socket. On macOS and Windows, check `podman machine list` and start the machine with `podman machine start`. On Linux, check the user socket:
Devsy cannot reach the Podman socket. On macOS and Windows, check `podman machine list` and start the selected machine with `podman machine start <machine-name>`. On Linux, check the user socket:

```bash
systemctl --user status podman.socket
Expand Down
Loading