Hologram: temporary AWS credentials on developer laptops

The instance metadata service, on a machine that is not an instance

The problem the project names in its first line is that storing AWS keys in source code is a bad idea and that few good alternatives exist without being terribly inconvenient.

The good idea it borrows is EC2 instance roles. On an EC2 instance, a special endpoint in the instance metadata service exposes temporary AWS API access credentials whose permissions are defined by the instance's role, configured at launch time. Applications designed against that endpoint need no secret keys in the repository at all, and the chance of malicious key use drops because there is no long lived key to steal. The catch is that this service only exists on EC2.

Hologram brings it to other hosts. It exposes an imitation of the EC2 instance metadata service on developer workstations, and because it speaks the same HTTP endpoint to calling SDKs, application code uses the same process in development and in production. The keys Hologram provisions are temporary, and the point of that is stated plainly in the overview: EC2 access can be centrally controlled without granting direct administrative access to developer workstations.

That is the whole thesis, and it is a good one. If you use Boto, the AWS Java SDK or GoAMZ, you are probably already configured to look for credentials at 169.254.169.254, which means adoption is mostly a matter of infrastructure rather than code.

The code is Go, the licence is Apache-2.0, and the project was built by AdRoll. The last push was on 2026-09-22, the same day as the 1.4 release, and the previous release was 1.3 in February 2023, so the release history is sparse.

Three processes, with LDAP in the middle

Hologram comes in three parts, and understanding how they divide the work tells you what you have to run.

hologram-server runs on an EC2 host in your AWS account. It services requests for credentials by authenticating clients against an LDAP database over SSH, and then requests temporary credentials using the IAM API. The AWS side of the system therefore lives inside your account, in a role it can assume, and it is the component that can mint credentials at all.

hologram-agent runs on OS X and Linux workstations. It exposes the metadata service interface locally and fetches credentials from hologram-server as needed, which means the agent is what makes the developer laptop look like an instance to the SDK.

The hologram CLI is the small piece that lets a user switch which IAM role they are currently using. That is the developer-facing control: a developer who needs elevated access for one command switches role, does the thing, and switches back, and the permission scope is decided centrally rather than by whoever handed out a key.

Two things follow from this shape. The authentication of a human is an SSH key lookup in LDAP, so the identity question is answered by your directory and not by AWS. And the credential issuance is an IAM API call from a server you control, so the temporary credentials come with a role and an expiry rather than being a secret that lives forever on a disk.

Your application code does not change

The compatibility claim is the one that makes this usable, and it is worth checking how specific it is.

Your software interacts with Hologram the same way it would with a production EC2 instance running an instance profile. You talk to the same 169.254.169.254 address and you receive credentials in the same format. The overview names the SDKs that are already set up this way: Boto, the AWS Java SDK, and GoAMZ.

In practice that means the developer experience is close to nothing new. There is no Hologram client library to learn, no custom credential provider to register in your application, and no environment variable to set differently between your laptop and your instance. The difference between local and production is entirely in the infrastructure, which is the property that makes the credential source a non-issue in code review and in deployment.

The same property is what makes the temporary credentials useful in review. Because the role is chosen centrally and the credentials are temporary, access to a production account from a laptop is a policy decision rather than a file that was copied around, and the audit trail lives in the IAM API and in your directory rather than in a shared secrets repository.

What does not change is the shape of the AWS call itself. If your application today hardcodes a credential source, Hologram does not fix that. It works when the application already defers to the metadata service, which is the common case for code written against modern AWS SDKs.

There are no binaries, so the build is the install

Hologram does not ship pre-compiled binaries, so installation is a build step, and the project has made that build reproducible with a container.

The provided container, adroll/hologram_env, includes all the dependencies and support for cross-compiling linux and osx binaries and for building deb and osx packages. The script is invoked from the directory where the source lives, and the README shows the full example of testing and building packages for all supported platforms:

./hologram.sh build_all

The output of that run is worth reading for what it produces: the dependency packages are fetched, the binaries are built, the test suite runs, and then the linux and osx packages are created, ending with a deb package for the agent and a deb for the server, plus an osx package.

For the full development environment with all the dependencies and cross-compiling support, there is a console target:

./hologram.sh console

Two configuration details matter before you package anything. The repository ships config/{agent,server}.json files, and the README notes that you will probably need to update them for your particular deployment, and that if you edit them the changes are included in the compiled packages. And the server host has to be baked into the osx package, which the Makefile does through a variable:

make build_osx HOLOGRAM_HOST=hologram.example.com:3100
make server_image REGISTRY=my.docker.registry.example.com:5000

The first sets the host that the agent on a developer's machine will call, and the second builds the deployable hologram-server image against your own registry. The Makefile also has targets for the build container itself, for the linux packages, for running the tests inside the container, and for opening a shell in it.

The prerequisites are the real adoption cost

Before any of this runs, the README lists what has to exist already, and the list is where the project is really decided.

There has to be an LDAP server holding user records with sshPublicKey attributes, and the attribute name is configurable. The keys in it have to match what the developers already have, because the ssh-agent has to be running on every workstation using the Hologram agent, configured to load the key that is stored in LDAP for that user.

There has to be an AWS account whose IAM permissions you can administer, and a developer IAM role, or something similar, with the minimum permissions you want developers to have by default. That role is the ceiling of what a developer can reach, and the CLI's role switching is how they move within it.

On the build side there has to be a Go development environment with the GOPATH already set up, unless you use the container, which the README points at as the reason you might not need one. The build script also expects a working docker installation on the local host, and the README notes that on OS X you would need Boot2Docker to run Docker inside VirtualBox.

The last prerequisite is the hardest to work around. Developers using Hologram must be on OS X or Linux, the built packages support Debian derivatives, and no Windows support is planned, though patches are welcome.

If your company already runs LDAP and hands out SSH keys through it, that is a good fit. If you authenticate through something else, the first piece of work is a shim, and the second is that the shim is authentication, which is not a place to improvise.

The toolchain in the tree shows how the project has aged

The dependency files are a good indicator of how this is maintained, and they show a project that has been kept working rather than kept modern.

The module file declares Go 1.17, and the dependency list is pinned to specific versions: the AWS SDK for Go at 1.44.160, the LDAP client, the SSH package, a protobuf runtime, and a test framework based on goconvey. The Dockerfile, on the other hand, builds on golang:1.27.1, so the toolchain used to build is much newer than the language version the module targets, which is a sensible way to keep an older module buildable with current compilers.

The build container installs a good deal beyond Go, and each package is there for a reason. fpm is installed as a Ruby gem to build the deb and rpm packages, cpio and rpm support the package formats, ruby-dev and xar support the macOS flat package, and bomutils is cloned to provide mkbom for the payload manifest that a macOS installer needs. The most interesting line is the llvm-lipo symlink: llvm-lipo combines the darwin amd64 and arm64 builds into a single universal binary, and since Apple's own lipo only exists on macOS, the container aliases the Debian LLVM tool so the universal build stays inside the container.

That is a well-kept build for a project whose last release before 1.4 was in 2023. The continuous integration badge in the README still points at Travis, which is the clearest sign of the age, but the build itself is the part that has been kept current.

When Hologram is the wrong answer

There is a much simpler approach for a lot of teams, and it is worth naming it before you deploy an LDAP-backed credential broker.

The simple approach is local AWS profiles: a developer has credentials in their own home directory, often issued by a scripted role assumption, and the code reads them as usual. The difference in approach is where the trust boundary sits. With profiles, a long lived or assumed key exists on the laptop and the central system governs who may create it, but the key is on disk. With Hologram, the laptop holds no AWS secret at all, the role and its expiry are decided centrally, and the developer only ever has a credential for the role they are currently switched into.

That extra property is worth real effort for a company with production credentials and a compliance function, and worth nothing for a team of two on a side project. The infrastructure cost is one EC2 host, a server process, an agent on every laptop, an LDAP directory with SSH keys in it, and a role hierarchy in IAM, and that cost does not scale down.

Two more boundaries. The Windows exclusion is real, and a team with Windows developers either needs a Unix environment for the agent or a different answer. And Hologram is not a secrets manager for other things: it provisions AWS credentials for EC2-style access, and it does not, on the evidence of the documentation, hold database passwords, API keys or anything else.

For a company that already has LDAP with SSH keys in it and an AWS account it administers, this is a tidy fit. For anyone else, the pieces it assumes are more work than the problem it solves.

Editorial conclusion

Hologram suits a company with an existing LDAP directory, an AWS account it administers, and a rule that long lived keys must never reach a laptop, and it is the wrong tool for a single developer or a team without LDAP, since it needs a server on EC2, an IAM role for each access level and an ssh-agent on every workstation. Verify first that your identity system can carry an sshPublicKey attribute, because that is the hinge the whole design turns on, and note that the project ships no pre-compiled binaries, so you are building and packaging the server, the agent and the CLI yourself.

Frequently asked questions

Official sources

1. AdRoll/hologram on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases