Skip to content

[docs] docs: document --session-state-dir flag and AWF_SESSION_STATE_DIR env var #1600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mossaka merged 1 commit into from
Apr 2, 2026
Merged

[docs] docs: document --session-state-dir flag and AWF_SESSION_STATE_DIR env var #1600

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
3 changes: 2 additions & 1 deletion docs/environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,9 +102,10 @@ The following environment variables are set internally by the firewall and used
| `AWF_DNS_SERVERS` | Comma-separated list of trusted DNS servers | `8.8.8.8,8.8.4.4` |
| `AWF_CHROOT_ENABLED` | Whether chroot mode is enabled | `true` |
| `AWF_HOST_PATH` | Host PATH passed to chroot environment | `/usr/local/bin:/usr/bin` |
| `AWF_SESSION_STATE_DIR` | Directory for Copilot CLI session state output (equivalent to `--session-state-dir`) | *(unset)* |
| `NO_PROXY` | Domains bypassing Squid (host access mode) | `localhost,host.docker.internal` |

**Note:** These are set automatically based on CLI options and should not be overridden manually.
**Note:** Most of these are set automatically based on CLI options and should not be overridden manually. `AWF_SESSION_STATE_DIR` is an exception — it is the environment-variable equivalent of `--session-state-dir` and can be set by users to configure a predictable session-state output path.

## GitHub Actions `setup-*` Tool Availability

Expand Down
8 changes: 7 additions & 1 deletion docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,9 @@ Options:
allowed to these servers (default: 8.8.8.8,8.8.4.4)
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to
this directory)
--session-state-dir <path> Directory to save Copilot CLI session state (events.jsonl, session
data). Writes directly during execution (timeout-safe, predictable
path). Also configurable via AWF_SESSION_STATE_DIR env var.
--enable-host-access Enable access to host services via host.docker.internal. Security
warning: When combined with --allow-domains host.docker.internal,
containers can access ANY service on the host machine. (default: false)
Expand Down Expand Up @@ -847,9 +850,12 @@ sudo awf \

**Agent Session State:**
- Contains structured conversation data written by Copilot CLI (e.g., `events.jsonl`)
- Location: `/tmp/awf-agent-session-state-<timestamp>/`
- Default location: `/tmp/awf-agent-session-state-<timestamp>/`
- View with: `cat /tmp/awf-agent-session-state-<timestamp>/events.jsonl`
- Useful for triage dashboards, benchmarking, and debugging Copilot CLI runs
- Use `--session-state-dir <path>` (or `AWF_SESSION_STATE_DIR`) to write session state to a
predictable path during execution — ideal for artifact upload in GitHub Actions where the
runner may time out before cleanup completes

**Squid Logs:**
- Contains all HTTP/HTTPS traffic (allowed and denied)
Expand Down